Add model-agnostic AI analysis layer with frontier-model hooks

Scripts/AIAnalysis/ — a pipeline that correlates findings across Veracode
scan types (SAST/DAST/SCA/container), validates them with a panel of Claude
models to reduce false positives, and chains related findings into risk paths.

Prepared for Mythos and future frontier models:
- models.json registry drives all model selection by role
  (triage/validate/deep-validate/correlate/chain/second-opinion). Enabling
  Claude Mythos 5 or a later model is a one-line config edit — no code change.
- providers.py shapes each request per model family: adaptive thinking for
  Opus/Sonnet, thinking omitted for Fable/Mythos (always-on), and server-side
  refusal fallbacks when a fallback_model is set. A not-yet-served model (404)
  is disabled for the run so the pipeline degrades gracefully.
- hooks.py exposes 9 operational hook points (pre_ingest ... report) so
  external tooling or a frontier model running alongside can observe/transform
  data at each stage without touching pipeline code.

Analysis capabilities:
- Deterministic cross-scan correlation (offline, stdlib-only, CI-safe):
  cross-layer CWE confirmation (SAST+DAST reachable), common flaw sources,
  shared CVE (SCA+container), dependency-usage links.
- Multi-model consensus FP validation (adversarial refute framing + quorum).
- Model-assisted risk chaining with combined severity, remediation order, and
  directed security-training recommendations.
- Structured outputs via output_config.format (json_schema) throughout.

Tests: 47 new tests (config/findings/correlation/hooks unit + pipeline
integration with a MockProvider, no API key needed). Full suite 163 passing.
Adds AIAnalysis flake8 job to the QAT workflow and documents the layer in the
READMEs.

https://claude.ai/code/session_015pBhzcxzBhLcAujgXrwsaz

Author: claude

.github/workflows/qat.yml

@@ -46,11 +46,20 @@ jobs:
             --count
         continue-on-error: true
 
+      - name: Run flake8 on AI Analysis layer
+        run: |
+          flake8 Scripts/AIAnalysis/ \
+            --max-line-length=120 \
+            --extend-ignore=E501,W503,E402 \
+            --statistics \
+            --count
+        continue-on-error: true
+
       - name: Run flake8 on tests
         run: |
           flake8 tests/ \
             --max-line-length=120 \
-            --extend-ignore=E501,W503 \
+            --extend-ignore=E501,W503,E402 \
             --statistics \
             --count
 

README.md

@@ -43,6 +43,19 @@ It wraps the Veracode REST and XML APIs with helper scripts, automated analysis
 | `vdb-purl-lte.sh` | Bash | Veracode vulnerability DB PURL lookup (lite) |
 | `veracode-installer.sh` | Bash | Install and configure Veracode CLI tooling |
 
+### Scripts/AIAnalysis — AI Analysis Layer
+
+Model-agnostic pipeline that correlates findings across scan types, uses Claude
+models to reduce false positives, and chains related findings into risk paths.
+New frontier models (Claude Mythos 5, future releases) are onboarded by editing
+`models.json` — no code changes. See [Scripts/AIAnalysis/README.md](Scripts/AIAnalysis/README.md).
+
+| File | Purpose |
+|---|---|
+| `analyze.py` | CLI entry point (offline correlation or full AI pipeline) |
+| `models.json` | Model registry — enable/disable models and assign roles |
+| `veracode_ai/` | Package: config, findings normalization, correlation, validation, chaining, hooks |
+
 ### Scripts/Dev — In Development
 
 | Directory | Contents |

Scripts/AIAnalysis/README.md

@@ -0,0 +1,142 @@
+# Veracode AI Analysis Layer
+
+A model-agnostic pipeline that sits on top of the Veracode scripts and adds
+**cross-scan correlation**, **AI-assisted false-positive reduction**, and
+**risk chaining** using one or more Claude models.
+
+It is built so that **Claude Mythos 5 and future frontier models can be
+switched on with a config edit** — no code changes — to validate and feed
+into the results, reduce false positives, and surface a deeper breadth of
+chained findings.
+
+---
+
+## What it does
+
+```
+ Veracode scans                    AI Analysis Layer                 Output
+┌──────────────┐   normalize   ┌────────────────────────────┐   ┌──────────────┐
+│ SAST (STATIC)│──────────────▶│ 1. Correlate (deterministic)│   │ risk chains  │
+│ DAST         │               │ 2. Validate  (model panel)  │──▶│ FP verdicts  │
+│ SCA          │               │ 3. Chain     (model)        │   │ correlations │
+│ Container    │               └────────────────────────────┘   └──────────────┘
+└──────────────┘                  driven entirely by models.json
+```
+
+1. **Normalize** every scan type into one `UnifiedFinding` shape.
+2. **Correlate** (offline, rule-based — runs in CI with no API key):
+   - **cross-layer confirmation** — same CWE found by SAST *and* DAST (present in code *and* reachable at runtime)
+   - **common flaw source** — static findings sharing a data-path source (fix once, remediate many)
+   - **shared CVE** — the same CVE in both SCA and container scans (confirmed in the deployed artifact)
+   - **dependency usage** — a vulnerable SCA component referenced by first-party flawed code
+3. **Validate** — every enabled validator model independently tries to *refute*
+   each finding; a consensus quorum decides confirmed vs. likely-false-positive.
+4. **Chain** — a chain-role model composes correlated findings into ordered
+   attack paths with combined severity, remediation order, and a recommended
+   security-training topic.
+
+---
+
+## Onboarding a new frontier model (Mythos / next model)
+
+Edit [`models.json`](models.json) — set `"enabled": true`. That's the whole change.
+
+```jsonc
+"mythos": {
+  "id": "claude-mythos-5",
+  "enabled": true,            // ← flip this on
+  "thinking": "omit",         // Fable/Mythos: thinking always on, send no config
+  "effort": "xhigh",
+  "max_tokens": 16000,
+  "fallback_model": "claude-opus-4-8",   // refusal fallback via server-side beta
+  "roles": ["deep-validate", "chain", "second-opinion"]
+}
+```
+
+The new model immediately:
+- joins the **validator panel** (a `deep-validate` vote runs alongside the existing votes),
+- runs in the **chain stage** (its chains are tagged with its model id so you can compare),
+- and requests are shaped correctly for its family (adaptive thinking vs. omit,
+  effort level, server-side refusal fallback).
+
+A model that isn't served yet (404) is disabled for that run and the pipeline
+degrades gracefully — so you can enable a registry entry ahead of GA without
+breaking CI.
+
+**Roles**: `triage`, `validate`, `deep-validate`, `correlate`, `chain`, `second-opinion`.
+
+---
+
+## Operational hooks
+
+Every stage fires a hook so external tooling — including a future frontier
+model running *alongside* the pipeline — can observe or transform the data
+without editing pipeline code:
+
+```python
+from veracode_ai.hooks import hooks
+
+@hooks.register("post_validate")
+def route_low_confidence(payload):
+    # payload = {"finding": ..., "verdict": ..., "votes": [...]}
+    # e.g. send split-vote findings to a frontier model for a second opinion
+    return payload
+```
+
+Hook points, in order: `pre_ingest`, `post_normalize`, `pre_correlate`,
+`post_correlate`, `pre_validate`, `post_validate`, `pre_chain`, `post_chain`,
+`report`.
+
+---
+
+## Usage
+
+```bash
+# Offline correlation only — no API key, CI-safe
+python analyze.py --rest findings.json --offline -o report.json
+
+# Full pipeline: correlate + FP-reduce + risk-chain
+export ANTHROPIC_API_KEY=...
+python analyze.py \
+  --rest findings.json \
+  --container image-scan.json \
+  -o report.json
+
+# Show the enabled model roster
+python analyze.py --print-models
+```
+
+`--rest` takes a Veracode REST Findings API response
+(`GET /appsec/v2/applications/{guid}/findings`, any scan type). `--container`
+takes Veracode CLI container scan JSON.
+
+### As a library
+
+```python
+from veracode_ai import load_registry
+from veracode_ai.pipeline import Pipeline
+from veracode_ai.providers import Provider
+
+pipeline = Pipeline(registry=load_registry(), provider=Provider())
+report = pipeline.analyze({"rest": "findings.json", "container": "image.json"})
+```
+
+---
+
+## Design notes
+
+- **Model-agnostic**: no model id is hard-coded in the pipeline; everything
+  comes from `models.json` via the registry.
+- **Structured outputs**: every model call uses `output_config.format`
+  (`json_schema`), so responses are guaranteed-parseable — no fragile text scraping.
+- **Family-aware requests**: `providers.py` sends `thinking={"type":"adaptive"}`
+  for Opus/Sonnet, omits `thinking` entirely for Fable/Mythos (where it's always
+  on), and attaches server-side refusal fallbacks when a `fallback_model` is set.
+- **Adversarial validation**: validators are prompted to *refute* findings, and
+  a finding only becomes a likely-FP on a quorum — biased toward not silently
+  dropping real bugs.
+- **Offline-first**: correlation needs only the standard library, so it runs in
+  every CI job; the model stages are additive.
+
+Requirements: `pip install -r requirements.txt` (only needed for the
+validate/chain stages; correlation is stdlib-only).

Scripts/AIAnalysis/analyze.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Veracode AI Analysis — CLI entry point.
+
+Correlate and validate findings across Veracode scan types with one or more
+Claude models. Model selection is driven entirely by models.json.
+
+Examples:
+    # Offline correlation only (no API key needed) — CI-safe
+    python analyze.py --rest findings.json --offline -o report.json
+
+    # Full pipeline: correlate + FP-reduce + risk-chain
+    export ANTHROPIC_API_KEY=...
+    python analyze.py --rest findings.json --container image.json -o report.json
+
+Onboarding a new frontier model (e.g. Claude Mythos 5): set its
+"enabled": true in models.json. No code change, no CLI flag.
+"""
+
+import argparse
+import json
+import sys
+
+sys.path.insert(0, __file__.rsplit("/", 1)[0])
+
+from veracode_ai.config import load_registry
+from veracode_ai.pipeline import Pipeline
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Veracode AI cross-scan analysis")
+    parser.add_argument("--rest", help="Veracode REST Findings API JSON (any scan type)")
+    parser.add_argument("--container", help="Container scan JSON (Veracode CLI)")
+    parser.add_argument("--config", help="Path to models.json (default: bundled)")
+    parser.add_argument("-o", "--output", default="ai-analysis-report.json")
+    parser.add_argument("--offline", action="store_true",
+                        help="Correlation only; no model calls (no API key needed)")
+    parser.add_argument("--print-models", action="store_true",
+                        help="Print the enabled model roster and exit")
+    args = parser.parse_args()
+
+    registry = load_registry(args.config)
+
+    if args.print_models:
+        for m in registry.enabled_models():
+            print(f"{m.key:8} {m.id:20} roles={','.join(m.roles)}")
+        return 0
+
+    scan_payloads = {}
+    if args.rest:
+        scan_payloads["rest"] = args.rest
+    if args.container:
+        scan_payloads["container"] = args.container
+    if not scan_payloads:
+        parser.error("provide at least one of --rest / --container")
+
+    provider = None
+    if not args.offline:
+        try:
+            from veracode_ai.providers import Provider
+            provider = Provider()
+        except RuntimeError as exc:
+            print(f"[WARN] {exc}\n[WARN] Falling back to --offline mode.", file=sys.stderr)
+
+    pipeline = Pipeline(registry=registry, provider=provider)
+    report = pipeline.analyze(scan_payloads, offline=args.offline or provider is None)
+
+    with open(args.output, "w") as f:
+        json.dump(report, f, indent=2)
+
+    print(f"[INFO] mode={report['mode']} findings={report['total_findings']} "
+          f"correlations={len(report['correlations'])} "
+          f"chains={len(report.get('risk_chains', []))}")
+    print(f"[INFO] wrote {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

Scripts/AIAnalysis/models.json

@@ -0,0 +1,56 @@
+{
+  "_comment": "Model registry for the Veracode AI analysis layer. To onboard a new frontier model (e.g. Claude Mythos 5) set enabled=true — no code changes required. Roles: triage | validate | deep-validate | correlate | chain | second-opinion",
+
+  "models": {
+    "opus": {
+      "id": "claude-opus-4-8",
+      "enabled": true,
+      "thinking": "adaptive",
+      "effort": "high",
+      "max_tokens": 16000,
+      "roles": ["triage", "validate", "correlate", "chain"]
+    },
+    "sonnet": {
+      "id": "claude-sonnet-5",
+      "enabled": true,
+      "thinking": "adaptive",
+      "effort": "medium",
+      "max_tokens": 8000,
+      "roles": ["validate"]
+    },
+    "fable": {
+      "id": "claude-fable-5",
+      "enabled": false,
+      "thinking": "omit",
+      "effort": "high",
+      "max_tokens": 16000,
+      "fallback_model": "claude-opus-4-8",
+      "roles": ["deep-validate", "chain", "second-opinion"]
+    },
+    "mythos": {
+      "id": "claude-mythos-5",
+      "enabled": false,
+      "thinking": "omit",
+      "effort": "xhigh",
+      "max_tokens": 16000,
+      "fallback_model": "claude-opus-4-8",
+      "roles": ["deep-validate", "chain", "second-opinion"]
+    }
+  },
+
+  "strategies": {
+    "fp_reduction": {
+      "mode": "consensus",
+      "validator_roles": ["validate", "deep-validate"],
+      "quorum_fraction": 0.5,
+      "batch_size": 10
+    },
+    "risk_chaining": {
+      "chain_roles": ["chain"],
+      "max_findings_per_request": 60
+    },
+    "second_opinion": {
+      "roles": ["second-opinion"]
+    }
+  }
+}

Scripts/AIAnalysis/requirements.txt

@@ -0,0 +1,4 @@
+# Veracode AI analysis layer
+# Offline correlation needs no dependencies (stdlib only).
+# The validate/chain stages require the Anthropic SDK:
+anthropic>=0.69.0

Scripts/AIAnalysis/veracode_ai/__init__.py

@@ -0,0 +1,23 @@
+"""Veracode AI analysis layer.
+
+Model-agnostic pipeline that correlates findings across Veracode scan types
+(SAST, DAST, SCA, container), validates them with one or more Claude models
+to reduce false positives, and chains related findings into risk paths.
+
+New frontier models (Claude Mythos 5, future releases) are onboarded by
+editing models.json — no code changes required.
+"""
+
+from .config import ModelConfig, Registry, load_registry
+from .findings import UnifiedFinding, normalize_findings
+from .hooks import HookRegistry, hooks
+
+__all__ = [
+    "ModelConfig",
+    "Registry",
+    "load_registry",
+    "UnifiedFinding",
+    "normalize_findings",
+    "HookRegistry",
+    "hooks",
+]