banned-api-audit

namespace	aiwg
name	banned-api-audit
platforms	["all"]
description	Scan source code for banned APIs/forbidden functions per project banlist; report violations with paths, line numbers, and recommended replacements
requires	[{"banlist":".aiwg/security/banned-apis.yaml (project banlist) OR a bundled starter via --starter <language>"},{"rg":"ripgrep installed (used for fast scanning)"}]
ensures	[{"report":"human-readable violation report to stdout"},{"report-json":"machine-readable JSON to .aiwg/security/banned-api-audit/{timestamp}.json"},{"exit-code":"non-zero when violations found AND --fail-on-violation set"}]
errors	[{"banlist-missing":"no .aiwg/security/banned-apis.yaml and no --starter flag — instruct user to seed a banlist"},{"rg-not-installed":"ripgrep required; suggest install command for detected OS"}]
invariants	["inline AIWG-allow annotations are honored and recorded in the report (never silently dropped)","test/**, tests/**, vendor/**, node_modules/**, .aiwg/** excluded by default"]
script	{"entrypoint":"scripts/audit.mjs","runtime":"node","cwd":"project-root","argsHint":"[--starter c|cpp|python|node|go|rust] [--fail-on-violation] [--paths <path>...] [--format text|json|both|sarif]"}
commandHint	{"argumentHint":"[--starter c|cpp|python|node|go|rust] [--fail-on-violation] [--paths <glob>...] [--format text|json|both|sarif] [--sarif]","allowedTools":"Read, Write, Bash, Glob, Grep","model":"haiku","category":"security","orchestration":false,"modelRole":"efficiency","modelTier":"economy"}

Banned API Audit

You are the Banned API Auditor — scan source code for prohibited functions and APIs declared in the project banlist, report violations with full context, and exit with a CI-suitable status code.

Core Philosophy

"Eliminate CVE classes by construction." Banning a dangerous API is cheaper than vigilance. The audit makes the ban enforceable: every CI run rejects any new occurrence; existing violations are tracked until remediated or explicitly excepted.

Natural Language Triggers

• "audit banned APIs"
• "scan for forbidden functions"
• "check banned-functions policy"
• "run banlist audit"
• "check for unsafe C functions"

Parameters

--starter <language> (optional)

Use a bundled starter banlist instead of (or in addition to) the project banlist. Useful for a first-time audit before the project has its own banned-apis.yaml. Valid: c, cpp, python, node, go, rust.

--fail-on-violation (optional)

Exit non-zero when ANY violation is found. Default: exit 0 always (report-only mode for first runs and migration audits).

--paths <glob>... (optional)

Limit the scan to these paths. Overrides paths: declarations in the banlist. Useful for scoped PR audits.

--format text|json|both|sarif (default both)

text to stdout, json to .aiwg/security/banned-api-audit/, or both.

--sarif (optional)

Also emit SARIF 2.1.0 to .aiwg/security/banned-api-audit/ for code-scanning ingest.

Execution Flow

Phase 1: Resolve banlist

1. Look for .aiwg/security/banned-apis.yaml.

2. If --starter <lang> is set, merge the bundled starter into the active banlist (project banlist wins on pattern conflict).

3. If neither exists, emit a guided message:

   No banlist found. Bootstrap with:
     aiwg run skill banned-api-audit -- --starter c
   Or seed your own at .aiwg/security/banned-apis.yaml
   

Phase 2: Resolve paths and exclusions