secure-harness-mcp

An MCP server for configuring and maintaining project-specific code checks.

Start by inspecting the repository and defining its security contract: endpoints, access rules, protected resources and deployment assumptions. Bind those requirements to readers and checks, and validate the checks before using their results. After an acceptable MVP is established, check new additions against that baseline. As the project evolves, review its requirements and extend or correct the harness, then establish a new measured baseline.

This is not a tool for autonomous vulnerability prediction on unseen repositories. Project-specific wiring and maintenance are part of the method. HISTORY.md records reader, rule and integration corrections.

Repository tools and research scope

Supply profile explicitly or set HARNESS_PROFILE; the MCP tools reject calls without a project profile. The existing profiles are examples for their own subjects, not suitable defaults for another repository.

Inventory describes configured coverage; it does not execute every listed analyzer or establish that a file is secure. A reported lane is not evidence that the lane ran successfully on that file.

The accompanying paper uses these packs and tools alongside study-specific measurement services and repair controllers in the paper's evidence tree. The standalone pack server does not itself provide the complete experimental build/test/attack battery, acceptance gate or rollback controller. The older snippet tools and proxy below are separate interfaces, not substitutes for that repository workflow.

The experimental gate protects recorded coordinates under fixed checks. Finite checks and aggregate counts do not guarantee all behavior or authorize release. Changes to policy, readers or deployment assumptions require review and a new measured baseline.

Related MCP server: pci-dss-mcp

Install the repository MCP server

From a source checkout:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python packlib/mcp_server.py --selftest
.venv/bin/python -m packlib.packtest
.venv/bin/python -m packlib.selftest_packs

The repository tools need Python and the MCP/PyYAML dependencies. They do not need Go or a model endpoint. Particular analyzer executions and controls may have additional dependencies. Inspect both failures and skipped controls: a skipped control is not a pass.

Launch the stdio server with:

HARNESS_PROFILE=your-project .venv/bin/python packlib/mcp_server.py

First create and validate projects/your-project.yaml; the example name above is not a shipped profile. For an MCP client's server configuration, use absolute paths:

{
  "command": "/absolute/path/to/secure-harness-mcp/.venv/bin/python",
  "args": ["/absolute/path/to/secure-harness-mcp/packlib/mcp_server.py"],
  "env": {"HARNESS_PROFILE": "your-project"}
}

The same inventory and module guidance are available without MCP, from the checkout root:

.venv/bin/python -m packlib.inspect_repo <profile> <repository>
.venv/bin/python -m packlib.inspect_repo <profile> <repository> <module-path>

The Homebrew formula is another installation path:

brew tap calvarado2004/secure-harness https://github.com/calvarado2004/secure-harness-mcp
brew install --HEAD secure-harness-mcp

It installs three commands: secure-harness-packs (repository MCP), secure-harness-mcp (older snippet MCP) and secure-harness-proxy (Python snippet proxy). The formula also installs Go for snippet build checks. Use secure-harness-packs when configuring the repository tools.

Policy packs

Packs separate rule ownership from runtime-specific readers and project facts:

packs/<runtime>/<axis>/<tier>/pack.yaml
orgs/<organization>/pack.yaml
projects/<project>.yaml

Shared rule identifiers and severity definitions live under packs/general/. Runtime packs bind applicable rules to detectors; project profiles supply facts and select the relevant packs. New syntax or requirements may need new reader or detector code, not just another YAML file.

The loader checks composition constraints, rejects held-out packs, and records justified suppressions. packtest separately checks controls, documentation and rule obligations; the runtime loader does not automatically execute that test suite on every load. Suppression records are exposed to consumers, but the paper's measured acceptance state does not include a suppression-count gate.

Readers exist for selected Python frameworks, browser JavaScript, Express, compose, nginx, SQL seeding and configuration credentials. Several other runtimes remain detect-only. Coverage depends on the selected profile and available detectors; consult the inventory and per-pack limits.

See packs/README.md for the current entry guide and docs/PACKS.md for design details. Historical design statements should be checked against packlib/loader.py, packlib/packtest.py and the current detector implementation before relying on enforcement.

Older snippet tools

secure_coding_mcp.py exposes secure_generate, harden_code, audit_code and score_code. It uses generate.py for a bounded generate/build/scan/repair loop. Its build check is Go-specific, and secure_generate defaults to language="go".

These tools can return code with residual findings after exhausting their repair budget. They do not implement the paper's repository acceptance contract or its project-specific functional checks.

Generation and repair require a configured model backend:

export SECURE_HARNESS_MODEL_URL=http://localhost:11434/v1
export SECURE_HARNESS_MODEL=your-served-model
export SECURE_HARNESS_KEY=your-endpoint-key
.venv/bin/python secure_coding_mcp.py

Use your endpoint's actual model identifier and supply credentials through the local environment; do not commit credentials. Audit and scoring still depend on the installed instruments. Model choice and tool availability can affect results; the paper does not establish model equivalence.

Older snippet proxy

The Python proxy processes a selected fenced Go/Python block in a /v1/chat/completions response. It does not inspect every repository edit, every language, or every code block. Responses without a recognized block pass through. On a harness exception, the Python handler returns the upstream content with a passthrough note; it is not a fail-closed repository gate.

secure-harness-proxy --port 8090

Configure SECURE_PROXY_UPSTREAM, SECURE_PROXY_KEY and SECURE_PROXY_MAX_ITERS as described in .env.example. Repair calls may incur model charges. Go/Python instrument requirements and the Go proxy implementation are separate from the repository pack server. Inspect the applicable implementation before treating any proxy as enforcement.

docs/TECHNICAL.md retains the snippet-layer reference. Its results and architecture should not be read as the current five-subject repository experiment.

License

MIT; see LICENSE.