Skip to main content

Security hypothesis analysis

Run, filter, export, and interpret CPG-backed security hypotheses through current CLI and MCP surfaces. See the examples and checks before applying it.

Technical Reference

The hypothesis workflow generates vulnerability hypotheses from the available knowledge base, evaluates them against a Code Property Graph, and reports confirmed, rejected, or inconclusive results. Use the result as input to the accountable security review and remediation decision.

Choose an interface

Use the CLI for local, explicit CPG files, detailed filters, incremental runs, report files, and fuzz-target export. Use MCP when an authorized agent session already has project context and needs a typed analysis result.

The current implementation boundaries are:

  • src/cli/analysis_commands/hypothesis_commands.py for CLI registration and arguments;
  • src/mcp/tools/query_suite/hypothesis.py for codegraph_security_hypothesis_run.

Inspect --help or the live MCP schema in the installed revision before automating either surface.

Run from the CLI

An analysis run requires an explicit CPG DuckDB path:

python -m src.cli hypothesis run --db path/to/project.duckdb

Select language, volume, priority, and output explicitly when reproducibility matters:

python -m src.cli hypothesis run \
  --db path/to/project.duckdb \
  --language C \
  --max 50 \
  --min-priority 0.5 \
  --format json \
  --output hypothesis-report.json \
  --human-language en

The JSON report includes the batch identity, execution counts, result counts, timing, and bounded hypothesis fields. Preserve the indexed Git revision and command arguments beside the report.

Limit the scope

Use a repeatable --category, comma-separated --cwe, or comma-separated --cve to focus a run. For changed files only, add --incremental --base-ref <git-ref>.

Use --exclude-fixtures, --exclude-mocks, --exclude-generated, or repeatable --exclude-category when those inputs are outside the assessment. Exclusions change the meaning of an empty result, so record them as evidence rather than hiding them in a wrapper script.

The selected CPG must match the repository revision being assessed. The command does not make an old graph current.

Inspect coverage and export targets

List the available knowledge-base entries and registered providers before choosing filters:

python -m src.cli hypothesis list-cwes --format json
python -m src.cli hypothesis providers

Export supported fuzzing or DAST targets with an explicit database and output directory:

python -m src.cli hypothesis export \
  --db path/to/project.duckdb \
  --format generic \
  --output fuzz_targets

The export formats are afl, libfuzzer, and generic. Review generated targets, build settings, input constraints, and execution safety before running them.

Run through MCP

Discover codegraph_security_hypothesis_run in the active client. The tool accepts an action of run, list_cwes, or list_providers, plus supported language, volume, priority, category, and human-language fields.

The MCP tool resolves the CPG from authorized runtime project context. Do not pass a raw db_path through an agent-facing call. Tool visibility and invocation policy are profile-dependent; a working call from the current client confirms availability.

For setup and typed-call rules, use the MCP operator guide.

Interpret results

Confirmed means the workflow collected evidence satisfying its current validation rules. Rejected means the evaluated hypothesis did not meet them. Inconclusive means the available graph or evidence could not settle the hypothesis.

Treat scores and aggregate metrics as properties of that run and labeled dataset, not universal product accuracy. Review source locations, query evidence, category, CWE mapping, exclusions, and graph freshness before triage. Validate high-impact findings manually and with the appropriate security tests.

Limits and safe use

  • Language patterns and CPG coverage determine which weaknesses can be evaluated.
  • A missing hypothesis records the result for the evaluated patterns and CPG coverage; review additional sources and runtime paths when assessing a weakness.
  • Generated fuzz targets are executable artifacts and require normal sandboxing and review.
  • Reports can contain repository structure and security-sensitive findings; control their storage.
  • Release acceptance still requires task-specific AppSec, QA, traceability, and runtime evidence.

Use threat modeling for system-level trust boundaries and SCA/SBOM for dependency risk; the three workflows answer different questions.

Report a documentation issue