armor-code/armorcode
Work with your ArmorCode tenant from your AI agent through the ArmorCode REST API, with guardrails: report on findings and risk, build and clean up your org hierarchy (groups, subgroups, hierarchy tags), manage teams, repositories and scans, and triage findings in bulk. Every change is planned, shown as a dry run, approved by you and verified, with automatic backups and a local audit log.
Changelog
1.2.1 — 2026-11-16
Ready for Anthropic's plugin directory. Nothing changes in what the skill or ac.py does.
- A README in the plugin folder says what the plugin runs, which hosts it connects to, how it handles the API key and what it stores locally. The directory shows it as the listing description, and its security scan compares the plugin's behavior against it.
- The approval hook runs from one script:
hooks/run-guard.shfinds Python 3.8+ (python3,pythonorpy) and runsguard.py. The directory doesn't accept hook commands with loops, extra variables or inline code. Behavior is unchanged: if no Python is found, it warns and lets the call through, andac.pystill refuses to send any change outsideapply. displayName: "ArmorCode"in the Claude manifest.tools/build.pychecks the directory's offline rules: the plugin README (40+ words), the license, file types and sizes (under 256 KiB, at most 512 files), no system files or symlinks, and hook commands that name one file under${CLAUDE_PLUGIN_ROOT}.- A new test runs the real hook command end to end on macOS, Windows and Linux.
1.2.0 — 2026-11-16
Works in any AI agent, not just Claude, and adds API behavior verified live on ArmorCode tenants. The repository is now armor-code/armorcode-skills (the old armorcode-claude URLs redirect).
Any AI agent
- Installs in OpenAI Codex, GitHub Copilot, Gemini CLI, Cursor and 70+ other agents, not just Claude:
- An Agent Plugins 1.0 manifest (
plugins/armorcode/plugin.json) for Codex, GitHub Copilot, VS Code and other conforming clients. - A Codex marketplace (
.agents/plugins/marketplace.json):codex plugin marketplace add armor-code/armorcode-skills. - GitHub Copilot CLI and Grok Build read the existing Claude-format marketplace.
npx skills add armor-code/armorcode-skillsinstalls the skill for any other Agent Skills client. The skill zip also unzips into~/.agents/skills/.- Tested with Claude Code, Codex CLI, Copilot CLI, Gemini CLI and the
skillsinstaller. CI repeats those installs on every change.
- An Agent Plugins 1.0 manifest (
- The approval hook in Codex: it blocks key exposure and edits to
~/.armorcode, including Codex'sapply_patchedits. Codex doesn't support hook approval prompts yet, so approvals there come from Codex's approval mode and the skill's plan-and-approve step. - The skill and docs no longer assume Claude. The setup reference has a per-agent table, and chat apps are pointed to ArmorCode's hosted MCP server for live data.
tools/build.pyalso validates the Agent Plugins manifest, the Codex marketplace andskills.sh.json, keeps every manifest's version in sync, and catches unquoted:in SKILL.md frontmatter (which silently drops the skill's metadata).
API learnings
API behavior verified live on ArmorCode tenants, and checked against ArmorCode's code and published API reference.
- SLA policies (
governance.md§3, rewritten):- Policies live at
/api/sla/template; the legacy/api/sla/configreturns[]. - Durations are milliseconds, not days as 1.1.0 said.
- Create a policy, assign it to a group with the new
plan group-update --sla-template-id, and apply it to existing findings withPOST /api/sla/template/{id}/recalculate. Recalculate is the UI's Save & Apply: it creates a new template id and takes effect at the next daily recalculation.
- Policies live at
- Jira without the UI (
integrations.md§6):- A complete mapping body.
- The
"webhook": truePUT for two-way status sync, and how to verify it. resolvedStatus/reopenStatusmust exist in the project workflow.- Moving groups between projects.
- Custom-field mapping, and which template variables render well or badly.
- Template updates with
PUT …/ticketUnifiedTemplate/{id}. - MULTI templates and grouped tickets (one issue for up to 50 findings).
- Runbooks (
governance.md§2):- A scheduled digest (
FINDING_SCHEDULE_REPORT): Quartz cron with seconds,timeZone, andfinding/email(one digest) vsfinding/createEmail(one email per finding). - Fixed trigger input ids.
- The lowercase
groupBykeys (cves, notcve). - Ticket template ids on
createTicket.
- A scheduled digest (
- Scan uploads:
- Uploads of one tool to one subgroup no longer overlap. Overlapping uploads don't deduplicate against each other.
plan scan-uploadwarns when an earlier upload is still processing.applywaits for it to finish, and stops without sending if it doesn't. - New notes for Prisma Cloud Compute CSV (image vs host files, and the
Hostnamededup trap), Prisma Cloud Redlock JSON, and Tenable CVSS v3, plugin output andtenable.plugin.family. - A recipe for scanners that aren't listed.
- Custom tool names must start with
custom-.
- Uploads of one tool to one subgroup no longer overlap. Overlapping uploads don't deduplicate against each other.
- Accept Risk, corrected (
findings.md§5):- The full direct body.
unsupressAfterDurationis epoch seconds. A millisecond value passes validation but never resurfaces the findings.PUT /api/findings/bulkisn't supported.
- Dashboards (
governance.md§5):PUT /api/custom-dashboard/{id}exists (1.1.0 said there was no full-dashboard PUT).- System dashboards can't be edited by API.
- Risk trend widgets need
aggregateBy: "Day"until a week of snapshots exists. - Team widgets need each group's assigned team.
- AQL:
groupTier,baseScore,CVSSVector,assetOwner, andslaDueDatewith'now()'arithmetic. Also the names that are rejected (tier,dueDate,slaStatus, …). - Correlation:
- A read-only inventory recipe, grouping by
correlationId. HostName:remediation groups.source/scanTypecan be lists in raw JSON.
- A read-only inventory recipe, grouping by
- Also:
- Exceptions'
acceptRiskOnExpiryacts on approval. - CMDB asset imports.
- GitLab repository matching and sync limits.
- Organization renames are UI-only.
- Group owners read back with email and name.
- Exceptions'
- Endpoint catalog: new rows for SLA, dashboard, risk trend and ticket-template endpoints. Every label was re-checked against the published API reference; endpoints not in it are marked Internal (may change without notice).
1.1.0 — 2026-11-16
First public release, from github.com/armor-code/armorcode-claude, under the Apache License 2.0.
- Install from GitHub. In Claude Code,
/plugin marketplace add armor-code/armorcode-claudethen/plugin install armorcode@armorcode; updates arrive withclaude plugin marketplace update armorcode. Desktop zips and the getting-started PDF are attached to each GitHub Release. - Windows support:
- The approval hook finds Python as
python3,pythonorpy, so it no longer needspython3on the PATH. If no Python 3.8+ is found, it warns instead of blocking every command. ac.pyno longer refuses key files on Windows because of POSIX permission bits that Windows doesn't have.- The macOS Keychain option now explains that it's macOS-only and points to
--token-env. - Output can't crash a Windows console with a legacy code page.
- Setup docs cover storing the key as a Windows user environment variable and running
ac.pywithpythonorpy -3.
- The approval hook finds Python as
- Hook false positives fixed: commands that mention a hostname like
www.armorcode.com, or that discard output with2>/dev/nullor2>&1, are no longer mistaken for edits to the local state folder~/.armorcode. - Tests run on macOS, Windows and Linux in CI.
1.0.0 — 2026-10-23
First release of the ArmorCode plugin for Claude.
armorcode-apiskill with a safety contract:- read-only by default;
- every change goes plan → approve → apply;
- finding text is treated as untrusted;
- the API key is never shown.
ac.pyguarded CLI (Python 3.8+, standard library only):- profiles per tenant, with keys from an environment variable, the macOS Keychain or a 0600 file;
- reads: groups, subgroups, hierarchy tree and lint, findings count/breakdown/list/export, AQL validation, scans, repositories, teams, users, roles, and the tenant's own OpenAPI spec;
- planners: group and subgroup create/update (read-merge-write), subgroup moves, hierarchy-as-code sync, repository mapping (single or CSV), team membership, bulk finding status/severity changes and moves (capped, with revert), scan upload, restore from backup, and raw requests with risk classification;
- apply: confirmation codes, plan expiry, resumable multi-step plans, automatic backups, post-change verification (including async jobs and "deleted but still there" checks), and a local audit log;
- planners for exceptions: one per group from a single AQL, plus submit/approve/reject/archive;
findings count --by FIELD,--org, andaql-checkthat breaks down zero-match queries;- hard write gate: no change is ever sent outside
apply, and read-only profiles can't apply; - plans signed per machine, redirects never followed with the key, https only;
plan rawgets the same guards: filter-key checks, counts, the 1,000 cap, and refusing standing rules or runbook backfills without an explicit flag;- handles rate limits as ArmorCode documents them: the 429 retry header, backoff with jitter, and proactive slow-down.
- Offline tests (
tests/) for the CLI's safety logic and the hook's decisions. - Approval hook for Claude Code and Cowork. It asks before
apply, before direct write requests to ArmorCode hosts, and before ArmorCode MCP write tools, showing the plan's steps. It blocks commands that would print the API key, and edits to the CLI's local state outsideac.py. - References: setup and key types, org model and hierarchy, findings, AQL v2 (live-validated), access control, governance, integrations, troubleshooting, and an endpoint catalog with Public/Internal stability labels.