Project Findings Onto Graph

---
name: project-findings-onto-graph
description: 'Use when graph-backed security analysis is needed: project SARIF or reviewer findings onto a program graph; build or query a multi-language graph; summarize Trailmark structure; map smart-contract entry points; compare two refs or snapshots; or hunt confirmed vulnerability variants with pattern or graph seeding. Select findings, build-program-graph, trailmark-structural, entry-point-analyzer, graph-evolution, or variant-hunt mode and supply its required inputs. Not for security-finding triage: use triage-security-finding. Not for unrelated remote, credential, publish, deploy, or irreversible work.'
---

# Project findings and graph-backed security analysis

Graph-backed analysis gives external findings, source structure, entry points, structural changes, and confirmed root causes a common evidence surface. The default `findings` mode projects SARIF or other supported exports onto an existing graph. The other modes build or query that graph, summarize a Trailmark snapshot, analyze smart-contract entry points, compare two snapshots, or hunt variants of a confirmed root cause. Imported severity remains authoritative, and graph reachability never proves data flow.

## Contract

| Field | Bound contract |
|---|---|
| Trigger | A graph-backed security analysis is needed: findings must be projected onto a graph, a multi-language graph must be built or queried, Trailmark structure must be summarized, smart-contract entry points must be mapped, two refs or snapshots must be compared, or variants of a confirmed root cause must be hunted. |
| Authority | Reversible local. Reads the supplied source, graph, refs, snapshots, and finding exports. Depending on mode, writes graph exports, annotations, declared links, structural or variant reports, or temporary snapshot worktrees; `entry-point-analyzer` is read-only and emits only chat output. Temporary worktrees are removed before completion; no remote mutation occurs. |
| Side effect | `findings` writes graph annotations, severity or source subgraphs, and optionally an augmented export; `build-program-graph` writes graph exports, preanalysis annotations, and optional links; `trailmark-structural` emits its summary or full payload; `entry-point-analyzer` emits a structured markdown report as chat output only and writes no file; `graph-evolution` and `variant-hunt` emit their named local reports. Roll back by deleting named artifacts, removing annotations by source tag, and removing any temporary snapshot worktrees. |
| Done | The selected mode's inputs are validated and its evidence is complete: findings are matched or explicitly unmatched with graph context and source severity preserved; `build-program-graph` has parser coverage, preanalysis, bounded queries, and limitations; `trailmark-structural` has its requested summary or full payload; `entry-point-analyzer` accounts for every file and classification; `graph-evolution` classifies every graph change; or `variant-hunt` triages every bounded candidate. |

## Inputs

- `mode` (optional, default `findings`): one of `findings`, `build-program-graph`, `trailmark-structural`, `entry-point-analyzer`, `graph-evolution`, or `variant-hunt`.
- `findings` mode: a program graph already built for the target repository and at least one graph-importable finding export. SARIF 2.1.0 is the standard format; reviewer annotations and other tool exports count when an importer or file-and-line anchors are documented. Optional preanalysis evidence and additional source exports may be supplied.
- `build-program-graph` mode: a target source directory, an optional explicit language list, an existing declared-links file for cross-boundary edges, and an optional external binary-analysis graph export when supported. The installed graph analyzer is required.
- `trailmark-structural` mode: a target directory and `summary` or `full` mode (default `full`). Trailmark must already be available; summary mode returns languages, entrypoints, and dependencies, while full mode returns the version-gated structural payload.
- `entry-point-analyzer` mode: a smart-contract codebase, an optional directory filter, and an optional project name. Supported inputs are Solidity, Vyper, Solana/Rust, Move Sui, Move Aptos, TON, and CosmWasm. The human-invoked `entry-points` command may supply the directory path.
- `graph-evolution` mode: `before_ref` and `after_ref`, each a git ref or an existing directory path; an optional language (`auto`, one language, or a comma-separated list); and installed Trailmark. Refs create temporary worktrees, while directory inputs are used directly.
- `variant-hunt` mode: a confirmed root-cause statement, the original bug location or vulnerable snippet, and the reachable project codebase. Optional inputs select ripgrep, Semgrep, or CodeQL; `pattern-search` or `graph-seeding`; a graph seed node; ranking weights; and an exclusion scope.

## Refusals

- In `findings` mode, will not build a missing graph as part of augmentation; switch to `build-program-graph` mode first.
- Will not install or upgrade the graph analyzer, or install Trailmark into the project; only `trailmark-structural` may use an ephemeral `uv run --with trailmark` probe, and that probe must not modify the project.
- Will not present call-graph reachability or taint-subgraph membership as attacker-controlled data-flow or vulnerability proof.
- Will not promote imported findings beyond their source severity or status.
- Will not widen a matching heuristic to force unmatched findings or variant candidates into the graph.
- Will not classify uncertain smart-contract access as confident; ambiguous restrictions remain `Restricted (Review Required)`.
- Will not generate an evolution report from one healthy snapshot, a malformed ref, or a language-mismatched empty graph.
- Will not perform file, VCS, credential, paid, published, deployed, or remote mutation in `entry-point-analyzer` mode.

## Procedure

1. **Select and validate the mode.** Use `findings` when no mode is named. Validate every required path, ref, export, root-cause statement, or graph seed at its trust boundary before running a mode. Reject an unknown mode or a missing required input with its exact name; never widen scope by guessing. **Done when:** one named mode has a validated input set.

2. **Mode `findings`: project exports onto an existing graph.**
   1. Verify the graph exists by loading it with the graph tool's API. If loading fails, return `blocked: no-graph` and direct the invoker to `build-program-graph` mode; do not build it in this mode. **Done when:** the graph is confirmed.
   2. Reuse preanalysis if present; otherwise run blast-radius, entry-point, privilege-boundary, and taint passes on the loaded graph. If preanalysis cannot be made available, continue only with that absence recorded and omit cross-reference claims. **Done when:** preanalysis evidence is available or its absence is explicit.
   3. Locate every supplied finding export and record its path and format. **Done when:** every input is recorded.
   4. Probe optional importers on the loaded graph object before using them. Skip an input that requires an unavailable importer and name the requirement; never invent a CLI flag or API. **Done when:** every importer is gated.
   5. Project each input with its native importer. If no importer exists, resolve each file-and-line finding to the graph node whose span contains the normalized location and record that the match was manual. Record matched findings, unmatched findings, and created subgraphs per source. **Done when:** every input has a projection result.
   6. Report matched and unmatched counts per source. Investigate path alignment or scope when unmatched counts are high, but do not widen the heuristic. Enumerate annotated nodes and subgraphs; SARIF severity subgraphs use `sarif:error`, `sarif:warning`, and `sarif:note`, while source subgraphs retain tags such as `sarif:<tool>`, `weaudit:<author>`, or `binary:<artifact>`. **Done when:** counts, nodes, and subgraphs are listed.
   7. Overlap severity subgraphs with `tainted`, `high_blast_radius`, and `privilege_boundary` sets. Attach the result as prioritization context without reclassifying the imported finding. **Done when:** graph context is recorded and source severity is unchanged.
   8. Emit an augmentation report ordered by source path and format, matched and unmatched counts, subgraphs, cross-reference highlights, skipped inputs, and reasons. **Done when:** the augmentation report is complete.

3. **Mode `build-program-graph`: build and query a full multi-language program graph.**
   1. Verify the installed graph analyzer is on PATH and importable from scripts. Record its version; if unavailable, report the installation gap and stop without installing or manually replacing the analysis. **Done when:** tool availability or the gap is recorded.
   2. Ask the installed build which languages it supports and detect which languages exist under the target. Treat documentation as non-authoritative; use the installed build's answers. Stop if nothing is parseable. **Done when:** supported and detected languages are recorded.
   3. Build the full graph for the selected languages, using auto-detection unless the invoker supplied an explicit list. Never sample the tree. When supplied and supported, incorporate an external binary-analysis graph export as an augmentation and record its provenance; otherwise report that augmentation is unavailable. **Done when:** the full graph is built and any binary augmentation is incorporated or its limitation is recorded.
   4. Run all preanalysis passes before dependent queries: blast-radius estimation with downstream and upstream annotations and `high_blast_radius`; entry-point enumeration with `entrypoints`, `entrypoint_reachable`, `untrusted_external`, `semi_trusted_external`, and `trusted_internal`; privilege-boundary detection with `privilege_boundary`; and taint propagation from untrusted and semi-trusted entry points into `tainted`, with trusted entry points generating none. **Done when:** all four passes complete.
   5. Execute requested queries with the version-safe vocabulary: direct callers and callees; paths between functions or from entry points to targets; transitive ancestor and descendant slices; `complexity_hotspots(threshold=N)`; `attack_surface()` (passing through newer `attributes` objects unchanged); summary and JSON export; named subgraphs; and structured annotations (`ASSUMPTION`, `PRECONDITION`, `POSTCONDITION`, `INVARIANT`) with a source convention of `llm`, `docstring`, `manual`, or `preanalysis`. **Done when:** every requested query returns evidence or a named version limitation.
   6. Probe method or attribute presence before every version-specific feature. On older builds, use the documented baseline or compute from the export, such as selecting edges whose endpoints are both in a named subgraph. **Done when:** every versioned feature is safely used or reported unavailable.
   7. Declare parser-invisible FFI, RPC, IPC, or contract edges in the analysis-root links file when needed. Use TOML `[[link]]` blocks with `source`, `target`, `kind`, `confidence`, and optional `description` or `target_external = true`; reject ambiguous endpoints, unknown internal endpoints, invalid enums, and malformed TOML. Record `configured_by` on declared edges and treat `proxy.external:<symbol>` nodes as system boundaries, not source functions. **Done when:** each required boundary link validates or no declaration is needed.
   8. Record the model emitted by the installed build: node kinds such as `function`, `method`, `class`, `module`, `struct`, `interface`, `trait`, `enum`, `namespace`, `contract`, `library`, `template`, and newer `proxy`, `schema`, `table`, `view`, or `procedure`; origins such as `source`, `proxy`, `binary`, or `synthetic`; edge kinds and confidence; and per-unit parameters, return and exception types, cyclomatic complexity, and branch metadata. **Done when:** metadata describes the installed build rather than documentation.
   9. Bound every security claim. Paths are call-graph reachability; `tainted` is reachability from an untrusted entry point, not interprocedural data flow. Verify data flow by hand, account for `uncertain` dynamic-dispatch edges, and do not treat proxy or binary nodes as source functions. **Done when:** claims use only the strength of their evidence.
   10. Write the requested JSON export containing summary, nodes, edges, and subgraphs, and record emitted proxy nodes, external endpoints, and origins. **Done when:** the export exists, or no export was requested.

4. **Mode `trailmark-structural`: summarize one target with Trailmark.**
   1. Confirm the supplied target exists and is a readable directory. **Done when:** the target boundary is validated.
   2. Check the `trailmark` command or Python module, with `uv run trailmark analyze --help` as an acceptable probe fallback. Record a version when available. An ephemeral `uv run --with trailmark` retry is allowed only to test the import and must not install into the project. If all checks fail, report `trailmark is not installed` and return. **Done when:** availability or the installation gap is recorded.
   3. Detect languages through `trailmark.parse.detect_languages`, falling back to `trailmark.query.api.detect_languages` for pre-0.3 builds. If the result is empty, report `Trailmark found no supported languages under target` and return. **Done when:** supported languages or the language gap is recorded.
   4. For `summary`, run only `trailmark analyze --language auto --summary <target>` (or its `uv run` fallback), and verify the detected languages, `Entrypoints:`, and `Dependencies:` are present. For `full`, construct `QueryEngine.from_directory(target, language="auto")`, run `preanalysis()`, and assemble version-gated `languages`, `summary`, `preanalysis`, `attack_surface`, `hotspots`, `proxy_nodes`, and every named subgraph with counts and sample IDs. Probe `subgraph_edges`, `type_references`, and other newer methods with `hasattr()`; preserve `attack_surface` attributes and explicit empty sections. **Done when:** the selected payload is assembled without a widened analysis.
   5. Verify and return the complete summary or full payload, including the version when captured, or the exact missing-field/import gap. **Done when:** every field required by the selected mode is present or its gap is named.

5. **Mode `entry-point-analyzer`: analyze state-changing smart-contract entry points.**
   1. Resolve the codebase or `entry-points` command directory to an absolute readable path. Detect languages from extensions and manifests: Solidity, Vyper, Solana/Rust with `solana-program`, Move Sui with `Move.toml` `edition`, Move Aptos with `Move.toml` `Aptos`, TON (`.fc`, `.func`, `.tact`), and CosmWasm with `cosmwasm-std`. If none is supported, report the unsupported codebase and stop. **Done when:** languages and scope are confirmed.
   2. Apply the optional directory filter and locate every contract or module file in scope. **Done when:** every in-scope file is located.
   3. For Solidity, use `slither . --print entry-points` when `slither` is available, then manually verify access classification; on failure or absence, use manual analysis and record the fallback. **Done when:** a foundation method is selected and recorded.
   4. Retain every externally callable, state-changing function and exclude read-only forms: Solidity `view`/`pure`; Vyper `@view`/`@pure`; Solana functions without `mut` accounts; Move non-entry `public fun`; TON `get` and read-only receivers; and CosmWasm `query` handlers. **Done when:** state-changing scope is complete.
   5. Classify each retained function as Public (Unrestricted), Role-Restricted, Restricted (Review Required), or Contract-Only (Internal Integration Points). Trace explicit roles and checks (`admin`, `owner`, `governance`, `guardian`, `operator`, `manager`, `minter`, `pauser`, `keeper`, `relayer`, `lender`, `borrower`, `onlyRole`, `hasRole`, sender equality, `assert_owner`, `#[access_control]`); preserve ambiguous dynamic checks as Restricted; and include callback/interface indicators such as `onERC721Received`, `uniswapV3SwapCallback`, `flashLoanCallback`, contract-caller checks, `tx.origin` guards, and cross-contract hooks. **Done when:** every function has one conservative category.
   6. Record signature, file and line, category, actual restriction evidence and implementation, inheritance, callbacks, and expected-caller notes. Do not infer safety from modifier names or apparent low state impact. **Done when:** every entry point has evidence.
   7. Emit the markdown report with project, timestamp, scope, languages, focus, summary counts for Public/Role-Restricted/Restricted/Contract-Only/Total, per-category tables, per-file accounting, and Analysis Warnings. **Done when:** every file is analyzed or explicitly warned.

6. **Mode `graph-evolution`: compare graph structure across two refs or snapshots.**
   1. Confirm both refs resolve or both directories exist. Run `trailmark --help`; if absent, report the installation gap and stop. **Done when:** inputs and Trailmark are valid.
   2. For git refs, create temporary `mktemp -d` worktrees with `git worktree add`; for directory inputs, use them directly. Confirm both snapshots are non-empty. **Done when:** two snapshot directories exist.
   3. Build a Trailmark graph and run preanalysis for each snapshot, export both JSON graphs, and verify non-zero, plausible node counts. **Done when:** both healthy exports exist.
   4. Run `trailmark diff --json --language {language}` with the same explicit language used to build the graphs. Never accept the default `python`; distinguish a healthy empty diff from a language-missed near-empty graph using the summaries. **Done when:** native diff JSON is captured and interpreted against healthy counts.
   5. Compute membership changes for `tainted`, `high_blast_radius`, `privilege_boundary`, and related subgraphs from the exports, using `graph_diff.py` when available or direct set differences otherwise. **Done when:** every changed set has added and removed members.
   6. Classify every change in priority order: new tainted paths; privilege-boundary changes; attack-surface growth, especially `untrusted_external`; high-blast-radius additions; cyclomatic-complexity increases greater than 3 on tainted or entry-point-reachable nodes; structural additions; and structural removals checked for replacement rather than silent deletion. **Done when:** every change has node or edge evidence and one category.
   7. Assign severity to every finding, including removals: CRITICAL for a new tainted path to a sensitive function or removed auth boundary; HIGH for a new high-blast-radius entry point or large tainted-node complexity increase; MEDIUM for new trust-boundary edges or moderate complexity increase; LOW for additions without entry-point reachability; and INFO for dead-code removal or complexity reduction. **Done when:** every classification has a severity.
   8. For refs, capture `git diff {before_ref}..{after_ref}` and attach source context to findings naming nodes or edges. For directory inputs, state that source-level VCS context is unavailable. **Done when:** source context is attached or its absence is explicit.
   9. Write `GRAPH_EVOLUTION_{project}_{before_ref}_{after_ref}.md` with summary metrics, critical changes and recommendations, attack surface, complexity, taint, blast radius, privilege boundaries, added and removed nodes and edges, methodology, preanalysis, refs, and honest limitations. **Done when:** every required section exists.
   10. Remove temporary worktrees after writing the report and record their removal. **Done when:** no temporary worktree remains.

7. **Mode `variant-hunt`: search variants of a confirmed root cause.**
   1. Require the root-cause statement and either the original location or a vulnerable snippet. Validate the location in the codebase when supplied; otherwise preserve and validate the supplied snippet before proceeding. If neither is present, return `blocked: root cause and original location or snippet required`. **Done when:** the root cause and one concrete source anchor are validated.
   2. Enumerate expansion axes: the dangerous operation, dangerous data, missing protection, enabling context, related identifiers, other manifestations, and edge cases including null comparisons, empty strings, zero versus null, unauthenticated callers, and boundary values. **Done when:** every independent axis is listed.
   3. Write an exact ripgrep, Semgrep, or CodeQL pattern that matches the known bug only. Run it and require one hit at the known location or supplied snippet; zero hits means `blocked: pattern does not match known bug`. If the preferred tool is unavailable, try the next available tool in the stated preference order and record the fallback; if all are unavailable, report the tool gap. **Done when:** the exact pattern is proven or the tool gap is reported.
   4. Generalize one element at a time from names to structure to semantics. Record each pattern, tool, match count, true positives, and false positives; revert any change producing more than 50% noise. **Done when:** the final pattern is stable at no more than 50% false positives.
   5. In `graph-seeding` mode, load an existing graph and resolve the seed. If no artifact exists, return `blocked: missing-graph-artifact` and direct the invoker to `build-program-graph` mode; malformed or missing nodes return `blocked: invalid node object` or `blocked: node-not-found`. Compute at most three hops, exclude the seed, confirmed vulnerabilities, out-of-scope nodes, and nodes without textual or symbol content, then bound to 50 candidates. Rank by at least three of degree centrality, clustering coefficient, path length, and structural similarity using equal or supplied weights; document truncation, label every result a review target, and feed it directly into triage. **Done when:** the bounded ranked candidate set is ready.
   6. Triage every pattern or graph candidate by reading its surrounding function, callers, and types. Check guards, sanitizers, type constraints, and whether callers can provide attacker-controlled input. Record a verdict, severity, confidence, and the evidence for every ruled-out candidate. **Done when:** every candidate is triaged.
   7. Write the variant report with root cause, location, methodology table, confirmed findings, grouped false positives, and a CI-ready regression rule from the strongest pattern. In graph-seeding mode include seed, hop bound, ranking dimensions and weights, and truncation. **Done when:** the complete report and regression rule are written.

## Failure and recovery

| Case | Handling |
|---|---|
| Findings | missing graph returns `blocked: no-graph`; missing preanalysis produces an explicitly unprioritized report; an absent importer skips only the affected input; malformed inputs report their path and continue; high unmatched counts trigger path-root review without heuristic widening; interruption returns collected sources and their completion states; rollback deletes the augmented export or removes source-tagged annotations. |
| Build-program-graph | a missing tool, import error, language detection failure, or unrun preanalysis stops the affected analysis and reports the gap; version-gated methods fall back to the baseline or export computation; rollback deletes exports and declared links, while in-memory annotations vanish with the engine. |
| Trailmark-structural | invalid target, missing Trailmark, no supported languages, import failure, missing summary field, or failed feature probe is reported without fabricated sections; empty pass outputs are valid and returned explicitly; partial output is labeled partial. |
| Entry-point-analyzer | an unsupported codebase returns no invented entry points; unparsable files remain in Analysis Warnings; Slither failures fall back to manual analysis; ambiguous access remains Restricted (Review Required); no source or repository mutation is attempted. |
| Graph-evolution | Trailmark absence, failed diff, a single failed snapshot, skipped preanalysis, or a language-mismatched empty diff stops report generation. Healthy non-zero summaries plus empty arrays mean structural stability. If cleanup is interrupted, remove temporary worktrees before retrying and report the incomplete state. |
| Variant-hunt | missing root cause, zero exact matches, excessive false positives, missing graph artifacts, missing or malformed seed nodes, zero candidates, and write failures return their named blocked result. If more than 200 candidates exist before triage, triage the first 200 and document the remainder; if the 50-candidate bound is exceeded, truncate by degree centrality and document it. Delete partial reports after a failed write. |
| Rollback | remove every named local artifact and temporary worktree created by the selected mode; no remote state is changed. |

## Output

- `findings`: an augmentation report ordered by source path and format, with matched and unmatched counts, annotated nodes, created subgraphs, tainted/high-blast-radius/privilege-boundary overlaps, skipped inputs, and source severity preserved.
- `build-program-graph`: an evidence report ordered by installed version and parser coverage, languages, graph summary, preanalysis, requested queries, model metadata, exports, and limitations; it states that reachability is not data-flow proof.
- `trailmark-structural`: the requested Trailmark summary with language, `Entrypoints:`, `Dependencies:`, and version, or the full JSON payload ordered as languages, summary, preanalysis, attack surface, hotspots, proxy nodes, subgraphs, and optional type-reference samples.
- `entry-point-analyzer`: the scoped markdown entry-point report with summary and per-category tables, file accounting, restriction evidence, callbacks, and warnings.
- `graph-evolution`: `GRAPH_EVOLUTION_{project}_{before_ref}_{after_ref}.md`, including metrics, all structural and security-relevant changes, severity, source context, and cleanup methodology.
- `variant-hunt`: a local variant report with root cause, original location, methodology, confirmed findings, false positives, ranked graph-seeded candidates when selected, and a CI-ready regression rule.