Proposal: Structured triage and provenance-aware component analysis for ADR detection

[shengqi-gensee]

Summary

I would like to propose an extension to ADR Detection that gives Tier 1
a structured way to request deeper component investigation and gives Tier 2
better provenance and decision semantics.

The motivation is to improve recall for security-relevant component behavior
that is not evident from the transcript alone.

I have a working prototype and would like maintainers' feedback on the design
and preferred contribution boundaries before submitting implementation PRs.

Motivation

ADR's fast/slow architecture is a good fit for this problem, but I encountered
three related limitations:

1. Tier 1 currently provides a mostly binary handoff. It cannot explicitly say
   that component behavior, object lineage, or source provenance is needed to
   resolve the risk.
2. Source inspection may cover only an entrypoint or invoked component, while
   relevant behavior can reside in imported implementation files or dormant
   registered components.
3. A single Tier-2 threat bit can conflate two different questions:
   • Is there evidence of a compromised component or malicious scenario?
   • Did the recorded trajectory produce an unauthorized effect?

These distinctions matter for cases where malicious component behavior is
present but was not exercised, an injected instruction was refused, or an
authorized/fixture workflow contains sensitive-looking operations without an
unauthorized effect.

Proposed direction

Structured Tier-1 handoff

Add an optional schema-constrained triage contract that reports:

• BENIGN_EXIT or ESCALATE;
• scenario/component risk;
• injection presence;
• unsafe plan, action, and observed effect;
• authorization status;
• evidence identifiers;
• whether deeper provenance is required, and why.

Malformed or internally inconsistent output would escalate rather than silently
exit. The existing stock text contract would remain the default.

Bounded, label-free provenance

Allow Tier 2 to inspect source-bound component facts when requested:

• registered component identity and declared capabilities;
• source artifact digest;
• local imported implementation files;
• structural function/import information;
• explicit unavailable or incomplete coverage states.

The provider would return no malicious/benign verdict or benchmark label.
Paths and traversal would be constrained, and source content would be treated
as untrusted evidence rather than instructions.

Separate component risk from observed effects

Optionally let Tier 2 report:

• component_or_scenario_risk
• observed_unauthorized_effect

Both would use ABSENT, PRESENT, or UNRESOLVED. Existing consumers could
continue receiving one compatibility decision derived from a configured axis.

The component-risk judgment would require concrete source, instruction,
data-flow, privilege, or resource-abuse evidence. Generic randomness, mocks,
empty results, missing source, or ordinary fixture behavior would not be
positive malicious evidence by themselves.

Preliminary development evidence

In a controlled ADR-Bench development comparison using the same Luna model for
both tiers:

Configuration	TP	FN	FP	TN	Recall	FPR	Accuracy
Stock ADR/Luna	33	9	30	231	78.6%	11.5%	87.1%
This proposal	40	2	28	233	95.2%	10.7%	90.1%

In our own provenance-flow (not public yet) comparison using the same Luna for both tiers:

Method	TP	FN	FP	TN	Recall	FPR	Accuracy
Stock ADR/Luna	59	37	1	95	61.5%	1.0%	80.2%
This proposal	96	0	5	91	100.0%	5.2%	97.4%

Does this problem and direction fit ADR's intended open-source detection architecture?

[pengyuzhang]

Thanks for writing this up before opening PRs — that's the right order, and the problem statement is concrete enough to respond to point by point. Here's where I land on each of the three pieces, plus one issue with the evidence.

Import-following provenance — accept. This is the one I'd take. It's a verified coverage hole, not a design preference: get_source_code hands Tier 2 a 21-line wrapper while the actual behavior sits in function/. access_auditor is the clearest example — the registered path is a FastMCP wrapper whose body is return audit_user_permissions(...), and the excessive-permission-scope logic is all in function/access_auditor.py, which Tier 2 never sees. Fixing it is bugfix-scale, touches one file, and doesn't change any output semantics.

One condition: a control run with docstrings and comments stripped. Two of the six vulnerable split-file servers describe their own vulnerability in prose (function/access_auditor.py says "excessive permission scope ... violating the principle of least privilege"), so some of the recall gain from widening file coverage could be label leakage rather than better reasoning. The stripped run separates those.

Structured triage contract — accept conditionally. Behind a config flag, default off, stock text contract preserved, fail-toward-escalate preserved. Low blast radius, and it hardens a parse path that has already needed one fix (your PR #44). Reasonable.

Dual-axis threat output — defer. It conflicts with how both benchmarks label ground truth, it makes published metrics ambiguous unless the selected axis is recorded in the analysis output, and the only evidence for it is the non-public provenance-flow dataset. This is the largest change and the least supported of the three.

On the evidence: the numbers argue against the framing. Only 2 of the 42 malicious tasks (7 and 8) use the six split-file servers, so the provenance fix — the part worth landing — can account for at most ~2 of the +7 TP. The other ~5 came from the triage contract and the axis-split semantics, i.e. from prompt and decision-rule changes rather than from provenance. The delta is presented bundled and attributed to the architecture story; without a per-component ablation, the headline is unsupported even taken at face value. The existing enable_threat_intelligence / enable_source_code / enable_policy toggles in config_detector.yaml should make that ablation straightforward.