examples: add atr-import community example (compile ATR YAML into AGT policies)#2308
Conversation
…olicies Builds on PR microsoft#908 (examples/atr-community-rules/sync_atr_rules.py) which introduced the ATR rule conversion mapping. That utility produces one bundled PolicyDocument with all rules merged. This change adds a real 'agentos atr-import' CLI subcommand that emits one PolicyDocument YAML per ATR category, which lets operators: * Drop the output directory into AGT's folder-merge policy layout where each governance.yaml maps to one threat class. * Apply AGT scope globs at the category level. * Filter at compile time by category, severity, or ATR ID prefix. A stdlib --watch mode polls the source tree and re-emits on mtime drift, with no third-party dependency. The new command reuses the conversion helpers from PR microsoft#908 rather than re-implementing them, so any future ATR schema drift is fixed in one place. The PR microsoft#908 example utility remains the single source of truth for the rule mapping. Tested end-to-end against the upstream ATR catalogue: 421 input files compile cleanly into 1681 detection rules across 9 category files. ATR upstream: https://github.com/Agent-Threat-Rule/agent-threat-rules (MIT) Signed-off-by: Adam Lin <adam@agentthreatrule.org>
🤖 AI Agent: docs-sync-checker — Docs SyncDocs Sync
|
🤖 AI Agent: breaking-change-detector — API CompatibilityAPI CompatibilityNo breaking changes detected. |
🤖 AI Agent: security-scanner — View detailsNo security issues found. |
🤖 AI Agent: test-generator — `examples/atr-import/import_atr.py`
|
🤖 AI Agent: code-reviewer — Action Items:TL;DR: 0 blockers, 2 warnings. The PR introduces a well-structured CLI tool for converting ATR YAML rules into AGT policies, but there are minor areas for improvement.
Action Items:
| Warnings | Follow-up PRs are fine. | |
|
🔴 Contributor Check: HIGH
Automated check by AGT Contributor Check. |
github-actions
Bot
added
the
needs-review:HIGH
PR Review Summary
Verdict: |
|
For the Contributor Check HIGH flag — context that may help reviewers: This PR is a direct follow-up on #908 (merged 2026-04-13), which added the ATR cross-reference layer under I'm the maintainer of Agent Threat Rules (https://github.com/Agent-Threat-Rule/agent-threat-rules, MIT licensed, v2.2.1, 419 rules across 10 categories). External production references:
Reachable at adam@agentthreatrule.org. Re: the AI-agent bot feedback:
Will ping here once the follow-up commit is in. |
Follow-up commit on microsoft#2308 addressing the ai-agent bot feedback: - agent-os/README.md: add `agentos atr-import` example block to CLI Tool section. Covers the common flows (compile, --out, --manifest, filters, --watch). Cross-references PR microsoft#908 and the upstream ATR repo. - agent-os/CHANGELOG.md: add Unreleased "Added" entry for the new CLI subcommand. - cmd_atr_import.py: add `_validate_cli_paths()` helper invoked at the start of `cmd_atr_import()`. Fails fast on a nonexistent atr_dir, a non-directory atr_dir, or an unwritable out_dir parent. Returns exit code 1 with a single-line error on stderr instead of letting the failure surface mid-compile. - tests: add TestCmdAtrImportValidation with three CLI-entry tests (nonexistent atr_dir, atr_dir-is-file, valid paths happy-path). Total test count goes from 9 to 12, all green locally. Signed-off-by: Adam Lin <adam@agentthreatrule.org>
|
Follow-up commit pushed (14c41c4):
This addresses the docs-sync-checker and code-reviewer warnings. The contributor-check HIGH flag should re-evaluate once the bot picks up the commit. |
github-actions
Bot
added
the
documentation
imran-siddique
left a comment
imran-siddique
left a comment
There was a problem hiding this comment.
TL;DR: 2 blockers, not mergeable yet.
| Sev | Issue | Location |
|---|---|---|
| ⛔ | HIGH-risk contributor flag - needs maintainer sign-off on design | repo-wide |
| ⛔ | No existing review coverage - 805 new lines adding a first-class CLI surface needs architecture validation | cmd_atr_import.py |
| Watch mode uses mtime polling (acceptable for now, follow-up for fsnotify) | cmd_atr_import.py |
Action: Holding for maintainer architecture review. The ATR-to-AGT mapping reuse from #908 is good, but promoting an example script to a CLI subcommand is a design decision that needs explicit sign-off.
imran-siddique
left a comment
imran-siddique
left a comment
There was a problem hiding this comment.
TL;DR: 1 blocker. Not mergeable in current form.
| # | Sev | Issue | Where |
|---|---|---|---|
| 1 | Block | Core CLI should not take a dependency on external non-stdlib projects like ATR | \cmd_atr_import.py\ |
#1: We avoid adding core dependencies on external libraries/specs beyond Python stdlib. The right path is: create a standalone repo (e.g. \�tr-agent-governance-examples) with a solid example showing the ATR-to-AGT compile flow, and own it as a community integration. We will support it via \�xamples/\ and community docs. This keeps AGT's core surface stable and lets the ATR integration evolve independently.
Suggested next steps: extract this into a new repo with good examples, and we can link it from our community/ecosystem docs.
imran-siddique
left a comment
imran-siddique
left a comment
There was a problem hiding this comment.
Agreeing with the prior review: this should not be a first-party CLI subcommand in agent-os core. ATR is an external project, and adding it to the core CLI creates a maintenance dependency we should avoid.
Recommendation: move to a standalone community example or plugin under \�xamples/atr-import/. The implementation quality is solid, just needs to live outside core.
|
Hey @eeee2345 — just checking in. Are you still working on addressing the review feedback? Happy to help if you have questions. |
|
Hi @imran-siddique — sincere apology for the lag. I missed your 5/17 review yesterday (looked at the comments thread but didn't catch the formal CHANGES_REQUESTED on the reviews tab) and ended up only addressing the AI-agent bot warnings rather than the architectural concern. That's on me. I agree with the architecture decision: this should not be a first-party CLI surface in agent-os core, and the ATR dependency should live in Plan for the next push (today, within a few hours):
If you prefer the standalone repo path ( Will push the restructure + ping here when ready. |
Address @imran-siddique's 5/17 CHANGES_REQUESTED review: agent-os core should not take a runtime dependency on the external ATR project. Move the integration to examples/atr-import/ so AGT's core surface stays stable and ATR can evolve independently. Changes: * Move agent-governance-python/agent-os/src/agent_os/cli/cmd_atr_import.py -> examples/atr-import/import_atr.py. Rewrite the argparse wiring to be a standalone parser (no longer a subcommand on `agentos`). Add a `__main__` block so operators run it directly: `python examples/atr-import/import_atr.py <atr_dir> --out <out_dir>`. * Move agent-governance-python/agent-os/tests/test_cmd_atr_import.py -> examples/atr-import/test_import_atr.py. Replace the direct `from agent_os.cli.cmd_atr_import import ...` with an importlib path load of the example file, so the tests run from `examples/` without the agent-os package needing to know about them. The PolicyDocument schema test now does an optional import: if the `agent_os` package is installed it uses the strict pydantic check, otherwise it falls back to a structural shape check. * Revert agent_os/cli/__init__.py to main (remove the atr-import subcommand registration on lines 17, 621-623, 652-657). * Revert agent-governance-python/agent-os/README.md (remove the `agentos atr-import` CLI Tool block). * Revert agent-governance-python/agent-os/CHANGELOG.md (remove the Unreleased Added entry). * Add examples/atr-import/README.md with usage docs, the relationship to PR microsoft#908's sync_atr_rules.py, the AGT_ATR_SYNC_PATH env hook, and the test invocation note. Tests: 12 of 12 pass locally (`pytest examples/atr-import/test_import_atr.py`). ATR-to-AGT rule mapping stays single-sourced in examples/atr-community-rules/sync_atr_rules.py (PR microsoft#908), reused by this example via importlib + the existing AGT_ATR_SYNC_PATH hook. No core dependency added. Signed-off-by: Adam Lin <adam@agentthreatrule.org>
|
@imran-siddique — restructure pushed (e1dd7e0). Took the Summary of the diff (158 insertions / 73 deletions across 6 files):
No core surface change, no new core dependency. ATR-to-AGT rule mapping still single-sourced in 12 of 12 tests pass locally: The bot warnings from the previous pass (docs-sync, code-reviewer, contributor-check) should reset since the file is no longer a core CLI surface. Happy to re-title this PR to |
eeee2345
changed the title
|
@imran-siddique — restructure pushed in e1dd7e0. Moved everything out of the core CLI into examples/atr-import/ alongside examples/atr-community-rules/ from #908. The core CLI no longer takes any ATR dependency. Ready for re-review when convenient. |
imran-siddique
left a comment
imran-siddique
left a comment
There was a problem hiding this comment.
TL;DR: 0 blockers, approve.
Clean restructure into examples/atr-import/ as discussed. No core surface changes, standalone script with own argparse. Nice README.
… policies) (microsoft#2308) * feat(cli): agentos atr-import compiles ATR YAML to per-category AGT policies Builds on PR microsoft#908 (examples/atr-community-rules/sync_atr_rules.py) which introduced the ATR rule conversion mapping. That utility produces one bundled PolicyDocument with all rules merged. This change adds a real 'agentos atr-import' CLI subcommand that emits one PolicyDocument YAML per ATR category, which lets operators: * Drop the output directory into AGT's folder-merge policy layout where each governance.yaml maps to one threat class. * Apply AGT scope globs at the category level. * Filter at compile time by category, severity, or ATR ID prefix. A stdlib --watch mode polls the source tree and re-emits on mtime drift, with no third-party dependency. The new command reuses the conversion helpers from PR microsoft#908 rather than re-implementing them, so any future ATR schema drift is fixed in one place. The PR microsoft#908 example utility remains the single source of truth for the rule mapping. Tested end-to-end against the upstream ATR catalogue: 421 input files compile cleanly into 1681 detection rules across 9 category files. ATR upstream: https://github.com/Agent-Threat-Rule/agent-threat-rules (MIT) Signed-off-by: Adam Lin <adam@agentthreatrule.org> * docs+test(cli): address bot warnings on agentos atr-import Follow-up commit on microsoft#2308 addressing the ai-agent bot feedback: - agent-os/README.md: add `agentos atr-import` example block to CLI Tool section. Covers the common flows (compile, --out, --manifest, filters, --watch). Cross-references PR microsoft#908 and the upstream ATR repo. - agent-os/CHANGELOG.md: add Unreleased "Added" entry for the new CLI subcommand. - cmd_atr_import.py: add `_validate_cli_paths()` helper invoked at the start of `cmd_atr_import()`. Fails fast on a nonexistent atr_dir, a non-directory atr_dir, or an unwritable out_dir parent. Returns exit code 1 with a single-line error on stderr instead of letting the failure surface mid-compile. - tests: add TestCmdAtrImportValidation with three CLI-entry tests (nonexistent atr_dir, atr_dir-is-file, valid paths happy-path). Total test count goes from 9 to 12, all green locally. Signed-off-by: Adam Lin <adam@agentthreatrule.org> * refactor: move atr-import from agent-os core CLI to examples/ Address @imran-siddique's 5/17 CHANGES_REQUESTED review: agent-os core should not take a runtime dependency on the external ATR project. Move the integration to examples/atr-import/ so AGT's core surface stays stable and ATR can evolve independently. Changes: * Move agent-governance-python/agent-os/src/agent_os/cli/cmd_atr_import.py -> examples/atr-import/import_atr.py. Rewrite the argparse wiring to be a standalone parser (no longer a subcommand on `agentos`). Add a `__main__` block so operators run it directly: `python examples/atr-import/import_atr.py <atr_dir> --out <out_dir>`. * Move agent-governance-python/agent-os/tests/test_cmd_atr_import.py -> examples/atr-import/test_import_atr.py. Replace the direct `from agent_os.cli.cmd_atr_import import ...` with an importlib path load of the example file, so the tests run from `examples/` without the agent-os package needing to know about them. The PolicyDocument schema test now does an optional import: if the `agent_os` package is installed it uses the strict pydantic check, otherwise it falls back to a structural shape check. * Revert agent_os/cli/__init__.py to main (remove the atr-import subcommand registration on lines 17, 621-623, 652-657). * Revert agent-governance-python/agent-os/README.md (remove the `agentos atr-import` CLI Tool block). * Revert agent-governance-python/agent-os/CHANGELOG.md (remove the Unreleased Added entry). * Add examples/atr-import/README.md with usage docs, the relationship to PR microsoft#908's sync_atr_rules.py, the AGT_ATR_SYNC_PATH env hook, and the test invocation note. Tests: 12 of 12 pass locally (`pytest examples/atr-import/test_import_atr.py`). ATR-to-AGT rule mapping stays single-sourced in examples/atr-community-rules/sync_atr_rules.py (PR microsoft#908), reused by this example via importlib + the existing AGT_ATR_SYNC_PATH hook. No core dependency added. Signed-off-by: Adam Lin <adam@agentthreatrule.org> --------- Signed-off-by: Adam Lin <adam@agentthreatrule.org>
2 participants
Summary
Following up on #908 which added the ATR cross-reference layer under
examples/atr-community-rules/, this adds the data path: anagentos atr-importCLI subcommand that compiles ATR YAML rules into Agent OS YAML policies.The #908 example produces one bundled PolicyDocument with all rules merged. This change emits one PolicyDocument per ATR category, which slots into AGT's folder-merge policy layout where each
governance.yamlmaps to one threat class. It also supportsscope-glob targeting and compile-time filters by category, severity, or ATR ID prefix.Scope
agent_os.cli.cmd_atr_importregistered asagentos atr-import <atr_dir>._extract_regex_patterns,_validate_regex,_atr_to_agt_rule) so the ATR-to-AGT mapping stays single-sourced.--watchmode uses stdlib mtime polling — no new dependency.--manifest <path>emits a JSON build manifest for CI pipelines.Verification
pytest tests/test_cmd_atr_import.py— 9 of 9 pass.ruff checkclean on new files.Why this helps
ATR is being adopted in Cisco AI Defense's skill-scanner and the MISP galaxy. Operators currently hand-roll the compile step or pin a copy of #908's example script. This makes that step a first-class CLI surface and keeps category granularity intact.
ATR is MIT-licensed. All commits are DCO
Signed-off-by.