[Feature] Security Scanning (capa audit)

[Minitour]

Description

CAPA already has some security primitives — blocked-phrase enforcement, tool output sanitization, and CLI prerequisite checks. However, there is no dedicated audit command for detecting supply-chain threats in installed agent capabilities.

Agent instructions are direct input to systems with terminal access. A skill with hidden Unicode characters (zero-width spaces, bidirectional overrides) can silently alter agent behavior — this is the "Glassworm" attack vector.

Motivation

• Skills are Markdown files that get loaded as prompts — they are effectively executable in the LLM context
• Hidden Unicode in a SKILL.md can hijack agent behavior without being visible in a code review
• Post-install tampering (manual edits to deployed files) can go undetected
• There is no mechanism to verify that what's on disk matches what capabilities.lock says should be there

Proposal

Introduce capa audit as a security scanning command that runs locally with zero external dependencies.

Scan types

Scan	What it detects
Hidden Unicode	Zero-width chars, bidirectional overrides, homoglyph substitutions in all SKILL.md, rules, and agent instruction files
Content integrity	SHA-256 hash of every deployed file vs. hash recorded in capabilities.lock — detects post-install tampering
Drift detection	Diff between what capa install would produce (from capabilities.yaml) and what's actually on disk — catches manual edits to .cursor/rules/, .claude/agents/, AGENTS.md, etc.
Lockfile consistency	Verify all entries in capabilities.lock have matching entries in capabilities.yaml (no orphaned packages, no missing refs)

CLI interface

capa audit                          # run all scans, human-readable output
capa audit --ci                     # exit 1 on any finding
capa audit --ci --format json       # machine-readable for CI pipelines
capa audit --ci --format sarif      # GitLab/GitHub code scanning
capa audit --scan unicode           # run only Unicode scan
capa audit --scan integrity         # run only content integrity
capa audit --scan drift             # run only drift detection

Severity levels

Severity	Meaning	Default action
critical	Hidden Unicode found, integrity hash mismatch	Block (exit 1)
warning	Drift detected, orphaned lockfile entries	Warn (exit 0 unless --strict)
info	All checks passed	Pass

Lockfile changes

Extend capabilities.lock to include content hashes for every deployed file:

skills:
  - id: web-researcher
    source: gitlab:myorg/skills@web-researcher
    resolved_sha: abc1234def5678
    deployed_files:
      - path: .cursor/rules/web-researcher.mdc
        sha256: e3b0c44298fc1c149afbf4c8996fb924...
      - path: .claude/agents/web-researcher.agent.md
        sha256: 7f83b1657ff1fc53b92dc18148a1d65d...

GitLab CI integration

# .gitlab-ci.yml
capa-audit:
  stage: validate
  script:
    - curl -LsSf https://capa.infragate.ai/install.sh | sh
    - capa install --check
    - capa audit --ci --format sarif
  artifacts:
    reports:
      sast: capa-audit.sarif
  rules:
    - changes:
        - capabilities.yaml
        - capabilities.lock

Acceptance Criteria

• capa audit runs all scans locally with no network calls
• Hidden Unicode detection catches zero-width chars, bidirectional overrides, and homoglyphs
• Content integrity check compares deployed file hashes against capabilities.lock
• Drift detection diffs expected vs. actual state of provider-specific files
• --format json and --format sarif produce valid, parseable output
• --ci flag sets appropriate exit codes (0 clean, 1 violation)
• capabilities.lock is extended with per-file content hashes