security-audit

security-audit is a local, file-driven audit layer for GitHub-based agent factories. It validates the artifacts your team produces, scores risk, emits GitHub-friendly reports, and keeps the policy surface inside this repository instead of scattering it across chat threads or ad hoc scripts.

This repository is designed so another coding agent can clone it, install it, and run the same checks without needing hidden context.

What it audits

• Artifact schema and metadata
• Inventory records against CODEOWNERS
• Permissions, hooks, prompts, MCP specs, telemetry, exceptions, and registry promotion records
• Shell / harness / prompt-injection patterns
• Cisco-style skill and MCP scan output, normalized into the local audit model
• Advisory and blocking audit modes
• GitHub-friendly output as text, JSON, SARIF, or PR-comment style markdown
• Failing audits include a Suggested fixes section that points to the change needed to pass

How the pipeline works

The audit flow is intentionally simple:

1. Parse local JSON, Markdown, shell, or Cisco scan files.
2. Normalize them into typed findings.
3. Apply policy and risk scoring.
4. Emit reports for humans or GitHub checks.
5. Block only when you choose blocking mode.

The repo is local-first and file-driven. There is no required runtime API server.

Installation

Option 1: install from source

Recommended for Claude Code, Hermes, and other coding agents.

git clone <repo-url> security-audit
cd security-audit

python3.11 -m venv .venv   # use any Python 3.10+ interpreter you have installed
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e .

After that, either of these works:

avatar-audit --help
python -m avatar_audit --help

Option 2: run directly from source

If you do not want to install the package, set PYTHONPATH=src:

PYTHONPATH=src python3 -m avatar_audit --help

First run

Validate the included fixtures:

avatar-audit validate fixtures/avatar/good

Run the combined audit in advisory mode:

avatar-audit audit fixtures/avatar/mixed --mode advisory

Run the combined audit in blocking mode:

avatar-audit audit fixtures/avatar/mixed --mode blocking

If you prefer module mode:

python -m avatar_audit audit fixtures/avatar/mixed --mode advisory

Commands

Command	Purpose
avatar-audit validate <path>	Validate artifact schema files
avatar-audit inventory-validate <path> --codeowners <file>	Check inventory metadata against CODEOWNERS
avatar-audit permission-lint <path>	Lint declared permissions
avatar-audit static-scan <path>	Scan shell or harness files for risky patterns
avatar-audit prompt-risk <path>	Scan prompts and skill files for injection risk
avatar-audit skill-scan <path>	Cisco-aligned alias for prompt/skill scanning
avatar-audit mcp-check <path>	Validate MCP server trust and token handling
avatar-audit mcp-scan <path>	Cisco-aligned alias for MCP validation
avatar-audit cisco-normalize <path>	Normalize Cisco scan output into the local audit format
`avatar-audit audit --mode advisory	blocking`
avatar-audit adversarial-test <path>	Run adversarial regression cases
avatar-audit exception-check <path>	Validate exception records and expiry
avatar-audit promote <path> --dry-run	Validate registry promotion records
avatar-audit telemetry-validate <path>	Validate telemetry redaction contract
avatar-audit pilot-pack <path>	Generate the synthetic 300-case pilot pack

Output formats

audit and cisco-normalize support these output formats:

• text
• json
• sarif
• comment

Examples:

avatar-audit audit fixtures/avatar/mixed --mode advisory --format text
avatar-audit audit fixtures/avatar/mixed --mode advisory --format json
avatar-audit audit fixtures/avatar/mixed --mode advisory --format sarif
avatar-audit audit fixtures/avatar/mixed --mode advisory --format comment

When audit finds failures in text mode, it prints a Suggested fixes section that reuses the deterministic remediation guidance attached to each finding. The JSON, SARIF, and comment formats carry the same remediation text for downstream consumers.

Repository layout

Path	Purpose
src/avatar_audit/	Security audit implementation
tests/avatar_factory/	Regression and pilot coverage
fixtures/avatar/	Good, bad, and mixed fixtures
docs/	Governance, rollout, and Cisco alignment notes
.omo/	Plan and evidence artifacts

What is already ready

• Schema, permission, inventory, telemetry, registry, and exception checks
• Prompt, hook, shell, and MCP policy scans
• Cisco-style aliases and Cisco scan normalization
• 300-case synthetic pilot pack
• Advisory and blocking modes
• GitHub-friendly text, JSON, SARIF, and PR-comment reports

What is still needed before company rollout

The engine is ready; the company deployment wiring is not.

• Connect the repo to the real company GitHub org, rulesets, and required checks
• Decide the execution package: GitHub Action, reusable workflow, container, or internal CLI
• Define the trigger points: pull request, push, scheduled run, or manual run
• Wire audit output to the company observability path: comment, SARIF, dashboard, Slack, or SIEM
• Calibrate false positives and false negatives against real internal samples
• Define the kill switch and rollback procedure for blocking mode
• Document who owns approval, exception handling, and policy updates
• Pin the release version that the company will pilot

See the rollout runbook for the operational checklist:

• Rollout runbook
• Governance model
• Cisco alignment notes

For other coding agents

If you are Claude Code, Hermes, or another coding agent, this is the shortest safe path:

1. Clone the repo.
2. Create and activate a Python 3.10+ virtual environment with python3.10, python3.11, or newer.
3. Run python -m pip install -e ..
4. Run avatar-audit --help.
5. Run avatar-audit validate fixtures/avatar/good.
6. Run avatar-audit audit fixtures/avatar/mixed --mode advisory.
7. Run PYTHONPATH=src python3 -m unittest discover -s tests/avatar_factory -q if you want a full regression check without relying on the installed entrypoint.

Development checks

Run the test suite:

PYTHONPATH=src python3 -m pytest tests/avatar_factory -q

Run the repository checks:

python3 scripts/check_plan_compliance.py .omo/plans/avatar-factory-security-audit.md
python3 scripts/check_scope_fidelity.py
python3 scripts/validate_workflows.py .github/workflows

Notes

• The repository was renamed from Threads_bot to security-audit.
• The codebase keeps the audit pipeline local and file-driven.
• Cisco support is intentionally an optional detection layer, not a replacement for the repo's policy model.