8000 feat(common): add shared cyber finding schema and evidence-gated report by drk-ram · Pull Request #2968 · xerj-org/xerj · GitHub
[go: up one dir, main page]
Skip to content

feat(common): add shared cyber finding schema and evidence-gated report - #2968

Open
drk-ram wants to merge 1 commit into
xerj-org:mainfrom
drk-ram:feat/cyber-finding-schema-2767
Open

feat(common): add shared cyber finding schema and evidence-gated report#2968
drk-ram wants to merge 1 commit into
xerj-org:mainfrom
drk-ram:feat/cyber-finding-schema-2767

Conversation

@drk-ram
@drk-ram drk-ram commented Nov 5, 2026
8000 Copy link
Copy Markdown
Contributor

What this changes, and why

Adds the shared xerj_common::cyber_finding schema and evidence-gated report that #2767 lists as a shared piece for every cyber scenario, with a spec in docs/cyber-finding.md.

  • CyberFinding: id, scenario (code_review, blackbox, fuzz_plan, exploitability, score, advisory), title, CWE, location (source_span for Cyber pack: cyber.code_review (taint/sink-guided source review) #2771, endpoint for Cyber pack: cyber.blackbox (attack-surface mapping and test planning, authorized targets only) #2772), severity, CVSS vector/score, evidence[] of corpus references (corpus, record id, kind advisory/fix_commit/poc/pattern, 40-hex pin, fetch date, optional pinned citation), status, confidence and abstain.
  • No finding without evidence: validate() refuses a non-abstained finding with empty evidence; CyberFindingReport::finalize turns it into an explicit abstention instead of guessing. Malformed locations (traversal, control characters, bad line ranges), CWEs, evidence pins/dates and score/severity mismatches are errors.
  • Scope: blackbox, exploitability and any endpoint finding require a cyber_scope::ScopeGuard via verify_with_scope; the window, trusted origin and every endpoint target are checked, an out-of-scope target refuses the whole report, and the work order is echoed in the report. finalize refuses these findings without a scope.
  • report_sha256 is the SHA-256 of the RFC 8785 canonical form (scope included, digest excluded). verify_json re-checks all invariants and the digest.
  • hub_evidence exposes jcs_canonicalize and crate-visible validators for reuse; no behaviour change there.

This is a typed library primitive; it is not a registered recipe, MCP tool, or scanner, and sends no traffic. Scope stays limited to engine/crates/xerj-common/, docs/ and CHANGELOG.md.

Refs #2767, #2769

Evidence

From engine:
cargo fmt -p xerj-common --check
PASS (exit 0).
cargo test -p xerj-common --lib cyber_finding --quiet
PASS: 16 passed; 0 failed.
cargo test -p xerj-common --lib --quiet
PASS: 402 passed; 0 failed.
cargo clippy -p xerj-common --lib --tests --no-deps --quiet -- -D warnings -A clippy::chunks_exact_to_as_chunks
PASS (the allowed lint is the existing packed_f32.rs one under this toolchain; nothing suppressed in code).

Checks

  • cargo fmt --all (CI runs rustfmt --check and clippy -D warnings) - cargo fmt -p xerj-common --check passes
  • Scoped release build of the crates touched: cargo build --release -j 32 -p <crate> - not run
  • cargo test -p <crate> passes - cargo test -p xerj-common --lib 402 passed
  • ES-YAML conformance suite at 0 failed - not run; no ES-compatible behaviour touched
  • New ES-compatible behaviour has a matching YAML case - N/A: no ES-compatible behaviour changes
  • Docs updated if user-visible behaviour changed - docs/cyber-finding.md, CHANGELOG.md
  • For non-trivial changes: the applicable audit in docs/CONTRIBUTION_REVIEW.md - not completed
  • Operational audit - N/A: API/spec documentation only; no install, deployment, extraction, publication, or privileged execution recipe.

Not run: release build, ES-YAML conformance, workspace-wide tests, recipe-runner integration (the runner does not exist yet).

Provenance

  • Written by: @drk-ram
  • Verified (commands run, output observed): the commands above; round trip across all six scenarios, empty-evidence refusal/abstention, CWE format, missing/out-of-scope/expired/untrusted scope refusals, scope echo and digest tamper detection, JCS digest determinism, location traversal and control-character refusal.
  • Assumed (not tested, and what would falsify it): callers classify InputOrigin correctly and supply a trusted clock; the digest proves integrity only, not that corpus citations are true.

@drk-ram
feat(common): add shared cyber finding schema and evidence-gated report
6683cf9 
Add xerj_common::cyber_finding: one typed finding (scenario, CWE, source
span or endpoint location, severity/CVSS, corpus evidence refs, status,
confidence/abstain) shared by the cyber pack scenarios.

Non-abstained findings must cite evidence; unsupported findings become
explicit abstentions when a report is finalized. Black-box and
exploitability findings, and any endpoint location, require a ScopeGuard
and echo the declared work order. Reports carry an RFC 8785 SHA-256
receipt. Expose hub_evidence::jcs_canonicalize and crate-visible
validators for reuse.

Refs xerj-org#2767, xerj-org#2769

Signed-off-by: Raghuvar Karthik Durga <177662415+drk-ram@users.noreply.github.com>
@cla-bot cla-bot Bot added the cla-signed label Nov 5, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cla-signed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@drk-ram
0