> **Status: proposed.** Plan of record for stig-analyzer, drafted with AI assistance and reviewed by @andunn. Exit criteria are tracked in the attached milestone issues and advance only on merged evidence. Thesis: stig-analyzer is an agent whose delivery vehicle is a CI/CD component. It applies composable GitLab building blocks (CI/CD Catalog, Duo Agent Platform, Knowledge Graph) to a hard sector problem: Defense Information Systems Agency Application Security and Development (DISA ASD) STIG compliance analysis, reducing manual checklist completion from weeks to minutes. Current position lives in the milestone trackers attached to this epic; dated decisions live in the repository's decision records. ## 1. Problem and opportunity Defense and intelligence programs must complete the DISA ASD STIG checklist for every accredited application, against the full control set of the tracked STIG release. The work is manual, repetitive, expert-gated, and repeated at every assessment cycle: each control requires reading the application's code and configuration, forming a judgment, and recording a verdict with evidence. GitLab already owns every substrate the automation needs: the pipeline that sees every change, the Knowledge Graph that indexes the codebase, the Duo Agent Platform that can reason over it, and the CI/CD Catalog that distributes the capability. stig-analyzer composes them into one adoptable unit. The opportunity is twofold: removing a compliance burden that consumes expert time at every assessment cycle, and demonstrating that composable platform primitives can carry a hard regulated-sector workload. The packaging pattern that emerges is reusable for other agentic workloads. Project: https://gitlab.com/gitlab-com/public-sector/stig-analyzer Demonstration: https://gitlab.com/gitlab-com/public-sector/stig-analyzer-demo Standards body: https://gitlab.com/gitlab-com/public-sector/reference ## 2. The ladder 1. Rung 1, CI-invocation: a CI/CD component whose jobs shell out to the pinned Duo CLI for an agentic session per control. Honest and shippable; the starting shape. 2. Rung 2, flow-native: the instruction pack externalized into versioned artifacts and a registry-v1 flow definition; the component becomes a thin delivery shim. 3. Rung 3, agent-deployed: the flow registered in the AI Catalog as a discoverable agent, released on a semver train, gated by an eval corpus. This is the major-milestone target state. ## 3. Technical goals Invariant properties the system must satisfy at maturity. Distinct from the milestones, which are sequenced states; each goal is testable on any given build. 1. Verdict quality and traceability: every verdict is grounded in retrieved evidence with file-and-line citations and is reproducible against the eval corpus within a stated tolerance; the four-state verdict vocabulary (finding, not a finding, not applicable, not reviewed) is exhaustively and honestly assigned, and "not reviewed" never silently substitutes for analysis. 2. Output contracts: a versioned, schema-validated JSON verdict contract sits at the seam between agent and pipeline, evolves additively within a major version, and fails loud on any contract violation rather than emitting degraded output. 3. Provenance and supply chain: rule packs, prompt packs, and images carry checksums and versioned provenance, so a consumer can verify exactly what analyzed their code; releases are corpus-gated so model or prompt drift cannot ship silently. 4. Deployment envelope: operable on GitLab SaaS and self-managed, with a credible path to airgapped and controlled-egress environments including self-hosted model backends behind the AI gateway; this sector's defining constraint, partly gated on upstream capability and pursued as a goal regardless. 5. Operational properties: control-level parallelism with bounded cost and runtime per control; batch analysis is resumable or idempotent; a scheduled heartbeat detects upstream drift (parser, model, contract) and fails loudly with a named next action. 6. Interoperability: standard formats in and out; the tracked STIG's XCCDF in, a reviewer-consumable checklist and STIG Manager integration out; a bridge to compliance evidence formats such as OSCAL is reserved for the adjacency milestone (M5). 7. Identity and least privilege: the agent runs under a non-human identity with the minimum role that supports read plus model access; no personal credential is load-bearing at maturity. 8. Generalization: the packaging pattern is reusable for a second benchmark workload without forking the architecture. ## 4. Milestones ### M1: Public-grade presentation The project presents itself to a reader arriving cold at publication grade: what it does, how it works, and how to adopt it. - The presentation restyle (branded hero, hand-authored SVG architecture and flow diagrams, house design language) and the reference conformance scaffolding are merged to the default branch, and the project avatar carries the brand glyph - The demonstration project is public, showing live agentic analysis of a synthetic application - The parent README links the demonstration ### M2: Initial capability release A consumer can pin a version and trust it. - A semver release is cut through the release lane - The component is listed in the CI/CD Catalog and installable from it - The tracked STIG release's path and version are single-sourced in the repository - The demonstration consumes a released version under a working non-human identity, green end to end ### M3: Quality substrate Verdict quality becomes measurable and drift becomes visible. - A rule-family-stratified eval corpus (a deliberate subset of the full control set, growing as families are exercised) is built, published, and baselined - A scheduled heartbeat pipeline runs: parser canary at the pin, single-rule smoke against a pinned fixture, rule-pack provenance verification, and an informational pin-versus-latest report, with failures auto-filing issues - An input-contract stability ADR is adopted: additive-only inputs within a major version, a deprecation window for removals ### M4: Agent-deployed (the major milestone) stig-analyzer becomes the reference implementation of the agentic component packaging standard, filling that named gap in the reference repo. - Instruction pack externalized: per-rule-family prompt templates, output JSON schema, and few-shots as versioned artifacts on their own semver - A registry-v1 flow definition executing those artifacts - A contract seam: the verdict JSON contract documented and stability-governed - The eval corpus gating releases - A catalog semver release train under discipline - AI Catalog registration: the agent discoverable and adoptable in the product's own terms - The packaging standard authored into the reference repo with stig-analyzer cited as its reference implementation ### M5: Adjacencies (all in scope, all strictly after M2) - An evidence-pipeline integration: analyzer verdicts feeding a control-evidence production line that bridges into program compliance records (the OSCAL path reserved in the interoperability goal) - A CIS GitLab Benchmark sibling: a GitLab-config self-assessment agent over that benchmark's recommendation set, with simulation-constructed ground truth, proving the packaging pattern generalizes to a second workload - A guided STIG Manager deployment path: an adopting program stands up its own STIG Manager instance in its own cloud account from assets the component already carries (the existing AWS path documented and generalized), so the checklist destination is as adoptable as the analyzer itself ## 5. Identity and entitlement rail (parallel to all milestones) - A group-level non-human identity with a Duo entitlement: deliberate scope, one agent identity so a new consuming project adds one include instead of provisioning its own credential - An interim personal-credential bridge, protected, masked, hidden, set out of band, until the non-human identity is provisioned - An empirical test of the provisioned identity on the CLI path (seat plus explicitly set default Duo namespace) before any upstream comment - An upstream signal path: reproduction evidence goes to the upstream items tracking service-account agentic auth only after that test, so the evidence is probative ## 6. Non-goals for this horizon - Operating a hosted STIG Manager service: the component's STIG Manager lane stays a consumer opt-in capability in the consumer's own cloud account - A fixture-based demonstration: the demonstration runs live analysis - Naming any adopting program or organization in these public artifacts - A full-coverage eval corpus before the stratified subset proves the harness ## 7. Risks and dependencies - Upstream product gaps in non-human agentic identity may hold past M2; the interim credential bridge mitigates, and the platform's evolving autonomous service-account execution support is the watch item - Pinned-tool drift under the hold-dont-chase policy: pins are held, bumps happen on a red heartbeat or in the deliberate refresh window - Model drift before the corpus exists: the heartbeat is the interim alarm, then the cheap tier under the corpus - Maintainer coordination: convention and direction changes are agreed among maintainers rather than assumed - Duo entitlement and billing shape for non-human identities is unsettled upstream and may reshape the identity rail ## 8. Success measures - The component is listed in the CI/CD Catalog and installable by pin - The demonstration pipeline is green end to end on a pinned release with live agentic analysis - Verdict quality is reported against the corpus baseline on every release, and no release ships without passing the corpus gate - Projects beyond the demonstration consume the component under the shared group identity - The packaging standard exists in the reference repo with stig-analyzer as its cited implementation