ARMOR v6 (armor-agent-plugin)
ARMOR (AI Risk Management & Operational Resilience) is an LLM-driven AI-guardrail posture pipeline packaged as a Claude Code / Copilot plugin (v6.0.0).
It audits any codebase on disk against a 53-row catalog of AI & agentic standards—normalised across the EU AI Act, NIST AI RMF, MITRE ATLAS, OWASP Top 10 for LLM Applications (2025), and the AI Incident Database (AIID / MIT AI Risk Repository)—and produces a schema-validated posture report describing, per guardrail, whether the project implements it, backed by deterministically cross-verified file:line citations.
Table of Contents
- Why ARMOR v6? Core Design Principles
- 6-Phase Pipeline Architecture
- Repository Layout
- Installation & Runtime Requirements
- CLI Reference & Usage
- Step-by-Step Disk-Queue Protocol Walkthrough
- Phase-by-Phase Deep Dive
- Phase 1:
load(Deterministic Python) - Phase 2:
triage(LLM Applicability Profiling) - Phase 3:
triage-audit(Adversarial Red-Team Loop) - Phase 4:
conform(LLM Conformance & Citation Verification) - Phase 5:
conform-audit(Adversarial Red-Team + Re-Verification) - Phase 6:
report(Deterministic Rollup & Schema Validation)
- Phase 1:
- Citation Cross-Verification & Anti-Hallucination Engine
- Scoring, Weighting & Remediation Ranking
- The 12 Guardrail Families & 53 Sub-Guardrails
- Catalog Subsystem & Content-Addressed Versioning
- Agent Wrapper (
armor-agent) & Verdict Contract - Output Directory Structure (
.armor/) - Hard Invariants & Security Guarantees
- Testing & Verification
1. Why ARMOR v6? Core Design Principles
Traditional static regex scanners produce high false-positive noise and cannot reason about architectural intent, while unconstrained LLM code reviews hallucinate file paths, invent line numbers, and suffer from sycophantic confirmation bias.
ARMOR v6 solves both problems through two non-negotiable architectural properties:
- Zero Internal LLM API Calls (Disk-Queue Exchange):
The calling IDE agent (Claude Code / GitHub Copilot) is the LLM. The Python runner never contacts Bedrock, OpenAI, Anthropic, or any external network service during an audit. Every LLM phase is a deterministic disk-queue exchange:
- The Python runner writes
<run_dir>/queue/<phase>.request.jsoncontaining the exact prompt instructions, input data, and requiredresponse_schema. - The agent inspects the repository, performs the analysis, and writes strict JSON to
<run_dir>/queue/<phase>.response.json. - The Python runner validates the response, enforces all invariants, and writes the phase artifact.
- The Python runner writes
- Deterministic Citation Cross-Verification:
Every non-gap conformance verdict (
implemented,partial,weak) must carry at least onerelative/path.ext:lineorrelative/path.ext:start-endcitation. The Python runner resolves each citation beneathproject_root, blocks..path traversal, checks file existence, and bounds line numbers against the actual line count of the file on disk. Any fabricated or out-of-bounds citation automatically demotes the guardrail verdict toinconclusive, marksdemoted_due_to_hallucination: true, and logs an immutable incident record to.armor/hallucination_log.jsonl.
2. 6-Phase Pipeline Architecture
The pipeline consists of 6 sequential phases: two pure-Python deterministic phases (load, report) bookending four LLM disk-queue phases (triage, triage-audit, conform, conform-audit), two of which are multi-round adversarial red-team loops bounded at MAX_AUDIT_REVISIONS = 3.
flowchart LR
P1["1. load<br/>(Python)"] --> P2["2. triage<br/>(LLM)"]
P2 --> P3["3. triage-audit<br/>(LLM Adversary <=3x)"]
P3 --> P4["4. conform<br/>(LLM + Citation Verify)"]
P4 --> P5["5. conform-audit<br/>(LLM Adversary <=3x)"]
P5 --> P6["6. report<br/>(Python + Pydantic)"]
| # | Phase | Driver | Mode | Run-Dir Artifact | Purpose |
|---|---|---|---|---|---|
| 1 | load |
Python | one_shot |
01_guardrails.json |
Resolve & normalise the 53-row AI standards catalog. |
| 2 | triage |
LLM | two_step |
02_triage.{json,md} |
Profile the codebase and tag each of the 53 guardrails applies, partial_scope, or n_a. |
| 3 | triage-audit |
LLM (Adversary) | two_step (loop <= 3) |
03_triage_audit.{json,md} |
Red-team every applicability decision (CONFIRM, REVISE, INVESTIGATE). |
| 4 | conform |
LLM | two_step |
04_conformance.{json,md} |
Score in-scope guardrails, enforce concrete remediations, and cross-verify file:line citations. |
| 5 | conform-audit |
LLM (Adversary) | two_step (loop <= 3) |
05_conformance_audit.{json,md} |
Red-team conformance verdicts & citations; re-verify all post-audit citations. |
| 6 | report |
Python | one_shot |
06_report.json + reports/posture_* |
Join all phases, compute weighted coverage & ranked suggestions, and validate against PostureReport. |
3. Repository Layout
armor-agent-plugin/
├── README.md # Comprehensive project & technical documentation
├── .gitignore # Ignores .armor/, __pycache__/, *.lock, etc.
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (v6.0.0)
├── agents/
│ └── armor-agent.md # Thin delegation wrapper -> emits fenced YAML verdict
└── skills/
└── armor/
├── SKILL.md # Agent-facing skill contract + mandatory telemetry gate
├── scripts/
│ ├── armor_run.py # 4-line runpy launcher shim
│ ├── armor/ # Core runtime Python package
│ │ ├── __init__.py # __version__ = "6.0.0"
│ │ ├── __main__.py # `python -m armor` entry point
│ │ ├── cli.py # `pipeline` subcommand dispatcher
│ │ ├── file_lock.py # Cross-platform exclusive file lock (stdlib only)
│ │ └── pipeline/
│ │ ├── __init__.py # Public pipeline surface re-exports
│ │ ├── state.py # RunDir, phase order, citation verifier, fingerprint
│ │ ├── load.py # Phase 1: Catalog resolution & normalisation
│ │ ├── triage.py # Phase 2: System profile & applicability triage
│ │ ├── adversary.py # Shared red-team request & delta engine
│ │ ├── triage_audit.py # Phase 3: Applicability red-team loop
│ │ ├── conform.py # Phase 4: Conformance evaluation & citation check
│ │ ├── conform_audit.py # Phase 5: Conformance red-team loop + re-verify
│ │ ├── report.py # Phase 6: Rollup, coverage, suggestions, MD/JSON output
│ │ ├── schema.py # Pydantic v2 PostureReport models (extra="forbid")
│ │ └── schemas/
│ │ └── posture_report.schema.json # Generated JSON Schema (byte-synced)
│ └── catalog/ # Offline catalog build subsystem (--update-catalog)
│ ├── ai_standards_versioning.py # Content-addressed SHA256 version commit helper
│ ├── refresh_catalog.py # Umbrella orchestrator (5 downloaders + generator)
│ ├── download_aiid_slim.py # AI Incident Database GraphQL downloader
│ ├── download_eu_ai_act_cellar.py # EU AI Act (CELEX 32024R1689) CELLAR downloader
│ ├── download_mitre_atlas.py # MITRE ATLAS YAML + JSON splits downloader
│ ├── download_nist_ai_rmf.py # NIST AI 100-1 & 600-1 PDF downloader
│ ├── download_owasp_llm_top10.py # OWASP LLM Top 10 (2025) PDF downloader
│ └── generate_guardrail_catalog.py # Normaliser -> 12 families / 53 sub-guardrails
├── references/
│ ├── architecture.md # Module-by-module architectural reference
│ └── ai_standards/ # Versioned 53-row catalog + standards metadata
│ ├── _catalog/
│ │ ├── latest.json # Pinned pointer -> 2026-05-14__b1ed6db3
│ │ └── versions/2026-05-14__b1ed6db3/
│ │ ├── guardrail_matrix.json # Consumed by Phase 1 load
│ │ ├── guardrail_matrix.{md,csv}
│ │ ├── guardrail_catalog.{json,md}
│ │ ├── source_coverage.json
│ │ └── manifest.json
│ ├── eu-ai-act/ # {latest.json, history.jsonl, versions/<v>/...}
│ ├── nist-ai-rmf/ # {latest.json, history.jsonl, versions/<v>/...}
│ ├── owasp-llm-top10/ # {latest.json, history.jsonl, versions/<v>/...}
│ └── mitre-atlas/ # {latest.json, history.jsonl, versions/<v>/...}
└── assets/
└── tests/ # 40-test pytest suite
├── conftest.py
└── pipeline/
├── _helpers.py
├── test_state.py
├── test_load.py
├── test_triage.py
├── test_triage_audit.py
├── test_conform.py
├── test_conform_audit_and_report.py
└── test_schema.py
4. Installation & Runtime Requirements
ARMOR requires Python 3.9+ (tested up to Python 3.14 with Pydantic v2).
| Package | Used By | When Required |
|---|---|---|
pydantic (>=2.0) |
armor/pipeline/schema.py |
Always (every pipeline run) |
requests |
catalog/download_*.py |
Only when running --update-catalog |
pyyaml |
catalog/download_mitre_atlas.py |
Only when running --update-catalog |
pytest |
skills/armor/assets/tests/ |
Running the test suite |
Everything else in the runtime uses the Python standard library (argparse, json, pathlib, runpy, dataclasses, hashlib, re, datetime, shutil, subprocess, os, sys, tempfile, threading, contextlib, and platform-selected msvcrt / fcntl).
pip install pydantic requests pyyaml pytest
5. CLI Reference & Usage
The package can be invoked either via the marketplace file-path launcher skills/armor/scripts/armor_run.py or as python -m armor when skills/armor/scripts is on PYTHONPATH.
# Check version
python skills/armor/scripts/armor_run.py --version
# -> armor 6.0.0
pipeline Subcommand Flags
python skills/armor/scripts/armor_run.py pipeline <project> [OPTIONS]
| Flag | Action | Description |
|---|---|---|
--phase {load,triage,triage-audit,conform,conform-audit,report} |
store |
Run a specific pipeline phase. |
--finalize |
store_true |
For two-step LLM phases: consume queue/<phase>.response.json, validate, and write the phase artifact (or advance the audit loop). |
--status |
store_true |
Print the active run directory path and the current state of all 6 phases. |
--all |
store_true |
Advance every phase runnable without an LLM, automatically finalizing any phase whose .response.json is already present, and stop at the first phase awaiting an LLM response. |
--catalog PATH |
store |
Override the default guardrail_matrix.json (or latest.json) path in Phase 1 (load). |
--audit-model NAME |
store |
Reserved model hint for adversary phases. |
--validate-report |
store_true |
Validate <project>/.armor/reports/posture_latest.json against the Pydantic PostureReport contract and exit (0 = valid, 1 = schema violation, 2 = missing file). |
--write-schema |
store_true |
Regenerate armor/pipeline/schemas/posture_report.schema.json from PostureReport.model_json_schema() and exit. |
6. Step-by-Step Disk-Queue Protocol Walkthrough
Below is a complete end-to-end execution trace showing how an IDE agent (or developer) drives ARMOR against a target project at /path/to/target-repo:
Step 1: Start a Fresh Run & Advance to Triage (--all or --phase load)
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --all
Output:
[load] wrote /path/to/target-repo/.armor/runs/2026-11-16T18-00-00Z/01_guardrails.json (53 guardrails)
[triage] request written: /path/to/target-repo/.armor/runs/2026-11-16T18-00-00Z/queue/triage.request.json
LLM must write response to: /path/to/target-repo/.armor/runs/2026-11-16T18-00-00Z/queue/triage.response.json
then run: python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase triage --finalize
[--all] stopped at triage: awaiting LLM response at /path/to/target-repo/.armor/runs/2026-11-16T18-00-00Z/queue/triage.response.json
Step 2: Fulfill Phase 2 (triage)
- The agent reads
queue/triage.request.json. - The agent writes strict JSON to
queue/triage.response.json. - Finalize Phase 2:
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase triage --finalize
Step 3: Prepare & Fulfill Phase 3 (triage-audit)
- Prepare the adversary audit request:
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase triage-audit
- The agent reads
queue/triage-audit.request.json, critiques each row (CONFIRM,REVISE, orINVESTIGATE), and writesqueue/triage-audit.response.json. - Finalize Phase 3:
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase triage-audit --finalize
- If the adversary issued
>= 1REVISEandrevision < 3, the runner updates the target rows, writes a bumpedtriage-audit.request.json, removes the old response, and prints:[triage-audit] auditor requested revisions; new request written. Drop a fresh response at .../queue/triage-audit.response.json and re-run with --finalize.
- Once converged (or at round 3), it writes
03_triage_audit.jsonand03_triage_audit.md.
- If the adversary issued
Step 4: Prepare & Fulfill Phase 4 (conform)
- Prepare the conformance request:
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase conform
- The agent inspects the codebase for every applicable guardrail, attaches
relative/path.ext:linecitations and codebase-specific remediations, and writesqueue/conform.response.json. - Finalize Phase 4:
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase conform --finalize
Step 5: Prepare & Fulfill Phase 5 (conform-audit)
- Prepare the conformance adversary request:
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase conform-audit
- The agent red-teams the conformance rows (using only the cited
file:linelocations), writesqueue/conform-audit.response.json, and finalizes:python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase conform-audit --finalize
Step 6: Generate & Validate Phase 6 (report)
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --phase report
python skills/armor/scripts/armor_run.py pipeline /path/to/target-repo --validate-report
Output:
[report] wrote .../06_report.json and /path/to/target-repo/.armor/reports/posture_latest.md
ok: /path/to/target-repo/.armor/reports/posture_latest.json conforms to PostureReport schema
7. Phase-by-Phase Deep Dive
Phase 1: load (Deterministic Python)
- Module:
skills/armor/scripts/armor/pipeline/load.py - Catalog Resolution:
- If
--catalog PATHis provided, resolvesPATHdirectly. - Otherwise checks
<skill_root>/references/ai_standards/_catalog/latest.jsonand resolvesversions/<version>/guardrail_matrix.json. - Falls back to walking parent directories for legacy
ai_standards/_catalog/latest.json.
- If
- Normalisation: Transforms each entry in
sub_guardrailsinto:{ "sid": "GR-01.1", "family": "GR-01", "family_name": "Risk & impact assessment", "description": "...", "verification_test": "...", "applicability_hint": "...", "implementation_hints": "...", "standard_refs": "EU AI Act Art 6, 9, 27 | NIST GOVERN-1, MAP-1, MAP-3, MAP-5 | ATLAS AML.M0017 | MIT ..." }
Phase 2: triage (LLM Applicability Profiling)
- Module:
skills/armor/scripts/armor/pipeline/triage.py - Context Collection (
_system_profile_inputs):- Reads up to the first
6,000characters of any present manifest/documentation file:README.md,README.rst,README.txt,pyproject.toml,package.json,pom.xml,build.gradle,Cargo.toml,go.mod,requirements.txt,Dockerfile,openspec/AGENTS.md,AGENTS.md,CLAUDE.md. - Lists sorted top-level directory and file names (skipping dotfiles except
.github/).
- Reads up to the first
- Validation:
- Ensures every loaded
sidis present exactly once (no unknown, duplicate, or missing SIDs). - Enforces
statusin{"applies", "partial_scope", "n_a"}and non-emptyreason. - Produces
02_triage.jsonand02_triage.md.
- Ensures every loaded
Phase 3: triage-audit (Adversarial Red-Team Loop)
- Modules:
adversary.py+triage_audit.py - Allowed Verdicts:
CONFIRM,REVISE,INVESTIGATE. - Loop Semantics:
- When the adversary outputs
REVISEfor a row,apply_deltas()mergesrevised_rowover the previous row (preservingsidand row order) and records a{sid, critique, before, after}entry inrevisions_applied. - When the adversary outputs
INVESTIGATE,{sid, critique}is appended toopen_questions. - Convergence: Converges immediately when
len(revisions_applied) == 0, or force-terminates atrevision == MAX_AUDIT_REVISIONS (3)withconverged: false. - Intermediate rounds persist to
.triage_audit_trail.jsonand are cleaned up upon completion.
- When the adversary outputs
Phase 4: conform (LLM Conformance & Citation Verification)
- Module:
skills/armor/scripts/armor/pipeline/conform.py - Scope: Includes only guardrails whose post-audit triage status is
appliesorpartial_scope(n_arows are excluded from LLM conformance evaluation). - Allowed Verdicts:
implemented,partial,weak,gap,inconclusive,n/a. - Non-Gap Verdicts (
NON_GAP):{"implemented", "partial", "weak"}— must include>= 1verified citation. - Mandatory Remediation Rules:
For verdicts in
{"gap", "weak", "partial", "inconclusive"},remediationis mandatory and must be:- Codebase-specific: Name real files/directories in the project and exact target paths for new artefacts.
- Action-leading: Start with an imperative verb (never
"Implement the guardrail"). - Concrete: Reference real entry points, functions, and config keys.
- Anchored: Directly satisfy the guardrail's
verification_test. - Free of banned boilerplate phrases:
"Implement the guardrail","Add CI enforcement + persistent audit trail","as appropriate","follow best practices".
Phase 5: conform-audit (Adversarial Red-Team + Re-Verification)
- Module:
skills/armor/scripts/armor/pipeline/conform_audit.py - Adversary Directions:
- (a) DOWNGRADE rows whose evidence is weak or fabricated;
- (b) UPGRADE rows you can defend with additional citations.
- The adversary may not invent new SIDs, change scope, or read source files beyond the
file:linecitations already present in the target rows.
- Post-Delta Citation Re-Verification:
After applying adversary revisions in each round, the runner re-runs
verify_citationacross every row innew_target. If a revisedNON_GAProw has no valid citations (or its new citations fail verification), the runner immediately demotes it toinconclusive, setsdemoted_due_to_hallucination = True, logs the rejected citations tohallucination_log.jsonlwith"phase": "conform-audit", and records the count inpost_audit_hallucinations.
Phase 6: report (Deterministic Rollup & Schema Validation)
- Modules:
report.py+schema.py - Joins
01_guardrails.json,03_triage_audit.json, and05_conformance_audit.jsonbysid. - Guardrails tagged
n_ain triage inheritverdict = "n/a". - Aggregates
open_questionsfrom both Phase 3 (triage-audit) and Phase 5 (conform-audit). - Validates the assembled report dictionary against
schema.PostureReportbefore writing bytes to disk (any schema drift aborts loudly). - Writes:
<run_dir>/06_report.json<project>/.armor/reports/posture_<iso>.json&posture_<iso>.md<project>/.armor/reports/posture_latest.json&posture_latest.md
8. Citation Cross-Verification & Anti-Hallucination Engine
Implemented in verify_citation(project, citation) (armor/pipeline/state.py):
Accepted Grammar
^([^:]+?)(?::(\d+))?(?:-(\d+))?$
Examples:
src/main.py(whole file)src/main.py:42(single line)src/main.py:10-25(line range)
Verification Algorithm
- Regex parse: Strip whitespace and match against
_CITATION_RE. No match ->(False, "unparseable citation"). - Path confinement (
..traversal protection): Resolve(project / rel).resolve()and checkp.relative_to(project.resolve()). IfValueErroris raised ->(False, "citation escapes project_root"). - File existence: Check
p.is_file(). If missing ->(False, "file not found"). - Whole-file citation: If no
:linepart is given ->(True, "ok"). - Line count check: Read file (
utf-8,errors="replace") and count lines (total). IfOSError->(False, "unreadable"). - Bounds check: Let
lo = int(start)andhi = int(end) if end else lo. Iflo < 1orhi < loorhi > total->(False, "line out of bounds (file has <total> lines)"). Otherwise ->(True, "ok").
Hallucination Logging (.armor/hallucination_log.jsonl)
Every rejected citation in Phase 4 (conform) or Phase 5 (conform-audit) is appended to <project>/.armor/hallucination_log.jsonl:
{"ts": "2026-11-16T18-00-00Z", "phase": "conform", "sid": "GR-01.1", "citation": "src/ghost.py:10", "reason": "file not found"}
9. Scoring, Weighting & Remediation Ranking
Verdict Weights (VERDICT_WEIGHT)
| Verdict | Weight | Included in Coverage Denominator? |
|---|---|---|
implemented |
1.0 | Yes |
partial |
0.6 | Yes |
weak |
0.3 | Yes |
gap |
0.0 | Yes |
inconclusive |
0.0 | Yes |
n/a |
— | No (excluded from denominator entirely) |
- Overall Coverage (
overall_pct&applicable_only_pct): $$\text{overall_pct} = \text{round}\left(100 \times \frac{\sum_{r \in \text{in_scope}} \text{VERDICT_WEIGHT}[r.\text{verdict}]}{|\text{in_scope}|},\ 1\right)$$ (Returns0.0ifin_scopeis empty.) - Per-Family Rollup (
by_family): Sorted ascending by(score_pct, family)so the weakest guardrail families appear first. Families where all guardrails aren/aare omitted fromby_family.
Remediation Suggestions Ranking (_suggestions)
All actionable rows (verdict in {"gap", "inconclusive", "weak", "partial"}) are ranked deterministically by:
-points_unlocked(round(1.0 - VERDICT_WEIGHT[verdict], 2)descending — sogap&inconclusive(+1.0) rank ahead ofweak(+0.7) andpartial(+0.4)).family_score_pct(ascending — weakest family first)._SUGGESTION_KIND_ORDER[verdict](gap: 0,inconclusive: 1,weak: 2,partial: 3).sid(lexicographical tie-breaker).
10. The 12 Guardrail Families & 53 Sub-Guardrails
| Family ID | Family Name | Sub-Guardrail Count | SIDs | Key Standards Mapped |
|---|---|---|---|---|
| GR-01 | Risk & impact assessment | 5 | GR-01.1 – GR-01.5 |
EU AI Act Art 6, 9, 13, 27, 43; NIST GOVERN-1/4, MAP-1/2/3/5, MANAGE-1..4 |
| GR-02 | Data governance | 5 | GR-02.1 – GR-02.5 |
EU AI Act Art 10, 15, 53; OWASP LLM02, LLM04, LLM08; ATLAS AML.M0006/7/14/18 |
| GR-03 | Transparency & disclosure | 4 | GR-03.1 – GR-03.4 |
EU AI Act Art 11, 13, 14, 50, 53; OWASP LLM09; NIST GOVERN-1/4, MAP-1, MEASURE-2 |
| GR-04 | Human oversight | 4 | GR-04.1 – GR-04.4 |
EU AI Act Art 14; NIST GOVERN-3, MAP-3, MANAGE-1..4; OWASP LLM06, LLM09, LLM10 |
| GR-05 | Robustness & accuracy | 5 | GR-05.1 – GR-05.5 |
EU AI Act Art 15, 43; NIST MEASURE-1/2/4, MANAGE-2/3; OWASP LLM05, LLM09, LLM10 |
| GR-06 | Adversarial security | 5 | GR-06.1 – GR-06.5 |
EU AI Act Art 15, 55; OWASP LLM01, LLM02, LLM05, LLM06, LLM07, LLM10; ATLAS AML.M0002/3/4/15/18/19 |
| GR-07 | Privacy & data protection | 4 | GR-07.1 – GR-07.4 |
EU AI Act Art 10, 12, 15; OWASP LLM02, LLM06; ATLAS AML.M0012, AML.M0018 |
| GR-08 | Fairness & non-discrimination | 4 | GR-08.1 – GR-08.4 |
EU AI Act Art 9, 10, 13, 14, 15, 27; NIST MAP-1/2, MEASURE-1/2; MIT 1.1 |
| GR-09 | Content safety | 4 | GR-09.1 – GR-09.4 |
EU AI Act Art 13, 15; OWASP LLM02, LLM05, LLM09; NIST GOVERN-4, MEASURE-2, MANAGE-2/3 |
| GR-10 | Logging, monitoring & incident response | 5 | GR-10.1 – GR-10.5 |
EU AI Act Art 12, 14, 19, 73; NIST GOVERN-1/3, MEASURE-2, MANAGE-4; ATLAS AML.M0016 |
| GR-11 | Supply-chain & component integrity | 4 | GR-11.1 – GR-11.4 |
EU AI Act Art 15, 53; OWASP LLM03, LLM05; ATLAS AML.M0007, AML.M0014 |
| GR-12 | Agentic autonomy & action safety | 4 | GR-12.1 – GR-12.4 |
EU AI Act Art 14, 15; OWASP LLM06, LLM10; ATLAS AML.M0018; MIT 5.2, 7.1, 7.4 |
| Total | 12 Families | 53 | GR-01.1 – GR-12.4 |
5 Standards Frameworks |
11. Catalog Subsystem & Content-Addressed Versioning
The offline catalog subsystem (skills/armor/scripts/catalog/) fetches public regulatory and technical standards and normalises them into _catalog/versions/<date>__<sha8>/.
- Content-Addressed Versioning (
ai_standards_versioning.py): Computes a deterministic SHA256 hash over all staged files (excludingmanifest.json, which contains a non-deterministicfetched_attimestamp) by hashingrelpath + \0 + file_bytesin sorted order.- If
latest.json["sha"] == sha: discards the staged directory and appends astatus: "unchanged"entry tohistory.jsonl. - Otherwise: moves the staged directory to
versions/<YYYY-MM-DD>__<sha8>/, updateslatest.json, and appendsstatus: "new"or"changed"tohistory.jsonl.
- If
- Refresh Orchestrator (
refresh_catalog.py):# Check if upstream standards have drifted (exit 0 = unchanged, 1 = drift) python skills/armor/scripts/catalog/refresh_catalog.py --check-only # Regenerate the 53-row catalog from local standards without hitting the network python skills/armor/scripts/catalog/refresh_catalog.py --skip-downloads # Full network refresh (runs all 5 downloaders + generator) python skills/armor/scripts/catalog/refresh_catalog.py
12. Agent Wrapper (armor-agent) & Verdict Contract
agents/armor-agent.md defines the armor-agent delegation wrapper. It routes arguments into the armor skill, enforces a mandatory self-targeting guard, and emits a deterministic fenced YAML verdict block.
Self-Targeting Guard
If <project_root> resolves to armor-agent-plugin, armor-agent, or plugins/armor-agent-plugin/ after path normalisation, armor-agent refuses to run and immediately emits verdict: fail with zeroed counts and:
notes: "self-targeting refused: armor-agent cannot audit itself"
Deterministic Verdict Rules (First Match Wins)
| Priority | Condition | Emitted Verdict |
|---|---|---|
| 1 | Any gap row (posture.gap > 0) OR hallucinations.demoted_rows > 0 |
fail |
| 2 | Pipeline aborted (any phase exited non-zero) | fail |
| 3 | Zero gap rows, but >= 1 weak row OR >= 1 open_question |
warn |
| 4 | Only implemented / partial / n/a / inconclusive rows AND 0 hallucinations AND 0 open questions |
pass |
13. Output Directory Structure (.armor/)
ARMOR is strictly read-only on the target project outside <project_root>/.armor/:
<project_root>/.armor/
├── runs/<YYYY-MM-DDTHH-MM-SSZ>/
│ ├── 01_guardrails.json # Phase 1 output (53 normalised rows)
│ ├── 02_triage.json # Phase 2 output (system_profile + applicability)
│ ├── 02_triage.md # Human-readable triage summary
│ ├── 03_triage_audit.json # Phase 3 output (converged applicability + audit_trail)
│ ├── 03_triage_audit.md # Human-readable triage audit trail
│ ├── 04_conformance.json # Phase 4 output (verdicts + verified/rejected citations)
│ ├── 04_conformance.md # Human-readable conformance table (*demoted* markers)
│ ├── 05_conformance_audit.json # Phase 5 output (post-audit rows + audit_trail)
│ ├── 05_conformance_audit.md # Human-readable conformance audit trail
│ ├── 06_report.json # Phase 6 Pydantic-validated PostureReport
│ ├── .triage_audit_trail.json # Transient state (present only mid-Phase 3 loop)
│ ├── .conform_audit_trail.json # Transient state (present only mid-Phase 5 loop)
│ └── queue/
│ ├── <phase>.request.json # Written by Python runner
│ └── <phase>.response.json # Written by LLM agent (unlinked after audit convergence)
├── reports/
│ ├── posture_<YYYY-MM-DDTHH-MM-SSZ>.json
│ ├── posture_<YYYY-MM-DDTHH-MM-SSZ>.md
│ ├── posture_latest.json # Latest validated PostureReport JSON
│ └── posture_latest.md # Latest full Markdown posture report
└── hallucination_log.jsonl # Append-only log of all rejected/fabricated citations
14. Hard Invariants & Security Guarantees
- No External LLM Calls: The Python runner never contacts an external LLM or network endpoint; all LLM interactions occur through local
.request.json/.response.jsonfiles. - Mandatory Citation Cross-Verification: Every
NON_GAP(implemented,partial,weak) verdict without at least one verified citation underproject_rootis automatically demoted toinconclusiveand logged tohallucination_log.jsonl. - Bounded Adversarial Loops:
triage-auditandconform-auditare strictly bounded atMAX_AUDIT_REVISIONS = 3; unresolved disputes surface asopen_questions. - Pre-Write Schema Enforcement:
06_report.jsonandposture_latest.jsonare validated againstPostureReport(extra="forbid") before bytes hit disk. - Byte-Synchronized JSON Schema:
posture_report.schema.jsonis enforced by tests to be byte-identical toPostureReport.model_json_schema(). - Path Confinement: Only
<project_root>/.armor/is written under the target repository, and..traversal in citations is rejected viaPath.relative_to(). - Self-Targeting Prevention:
armor-agentrefuses to audit itself.
15. Testing & Verification
ARMOR ships with a 40-test pytest suite under skills/armor/assets/tests/ covering every phase, invariant, error condition, hallucination demotion path, audit loop convergence/force-termination, and Pydantic schema constraint.
python -m pytest skills/armor/assets/tests -v
Test Coverage Breakdown (40 Tests)
| Test Module | Tests | Behaviours Verified |
|---|---|---|
test_state.py |
10 | Canonical PHASES tuple; new_run/current_run round-trip; fresh pending status; require_phase_done guard; file, line, and range citation verification; out-of-bounds line rejection; missing file rejection; .. path traversal blocking; project_fingerprint change detection on edit. |
test_load.py |
3 | Normalisation of SIDs, families, and family_name; artifact persistence equality; explicit --catalog path resolution. |
test_triage.py |
5 | Request generation with all SIDs + README.md manifest preview + response_schema; happy-path JSON/MD output and by_status counts; rejection of unknown SID, missing SID, and invalid status. |
test_triage_audit.py |
3 | Immediate round-1 convergence on all CONFIRM; 2-round convergence after a REVISE delta (audit_trail length 2); force-termination at MAX_AUDIT_REVISIONS = 3 with converged: False. |
test_conform.py |
4 | Exclusion of n_a rows from in_scope; valid citation retention; bogus citation demotion to inconclusive + hallucination_log.jsonl append; rejection of out-of-scope SIDs. |
test_conform_audit_and_report.py |
6 | Adversary REVISE downgrade (implemented -> weak); adversary REVISE with fabricated citation auto-demoted to inconclusive; Phase 6 report join + posture_latest.{json,md} pointers; 50% coverage calculation & n/a-only family exclusion; suggestion ranking by points_unlocked (+1.0 before +0.7, 15% mixed coverage); open_questions aggregation. |
test_schema.py |
9 | PostureReport validation (overall_pct == 50.0); rejection of unknown top-level keys, unknown row keys, invalid verdicts, malformed generated_at timestamps, and out-of-range percentages; zero-drift validation of persisted report; schema persistence (title == "PostureReport"); byte-equality between packaged posture_report.schema.json and PostureReport.model_json_schema(). |
Author & Attribution
- Artifact:
armor-agent-plugin(v6.0.0) - Author: Aveek Sengupta (
aveekforyou@gmail.com)
Metadata
Release files for armor-agent-plugin 6.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| armor_agent_plugin-6.0.1.tar.gz | 171.6 kB | With provenance | Details for armor_agent_plugin-6.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| armor_agent_plugin-6.0.1-py3-none-any.whl | Python 3 | none | any | Details for armor_agent_plugin-6.0.1-py3-none-any.whl |
Total release size: 290.8 kB
Release files / armor_agent_plugin-6.0.1.tar.gz
| Download URL | armor_agent_plugin-6.0.1.tar.gz |
|---|---|
| Size | 171.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f44b8495e4a87788f3dc753ccb0dcf2e681529e5fe6ad218f834d9a65f502976
|
|
BLAKE2b-256 checksum How to use checksums |
18c66a9ce2cc27d2f8410252ff9b1c8144489d2616f653639d5d1ddf231bbc83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / armor_agent_plugin-6.0.1-py3-none-any.whl
| Download URL | armor_agent_plugin-6.0.1-py3-none-any.whl |
|---|---|
| Size | 119.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9177a5822d1ff7d74cf430372376c0e9cdb804074fe869c485bacb3df6677b63
|
|
BLAKE2b-256 checksum How to use checksums |
d668c2c6b946c106ad3665f87bb8a05857a3595a057fc178f2374d0fc09ba628
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for armor-agent-plugin 6.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for armor_agent_plugin-6.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.