Executes a "audit first, confirm next, remediate last" security loop on a complete codebase. The first run can only read and report; the remediation phase must be explicitly authorized by the customer after seeing the specific findings, files, behavior changes, tests, and rollback plan.
Customer-readable explanation
What this skill can do
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Perform an overall security check on a code path | Read repository rules, architecture, dependencies, entry points, permission boundaries, and code implementation | Project security overview, attack surface, Findings, evidence, and coverage gaps |
| Determine whether a vulnerability affects the project | Compare against dependencies, versions, configuration, deployment method, and call paths | Hit/not hit/unknown conclusion and evidence chain |
| Remediate audit findings | First provide a remediation batch preview, then remediate item by item after confirmation | Precise file scope, diff, tests, and per-item status |
| Verify whether the remediation is truly effective | Reproduction, direct testing, related regression, rescanning, and independent review | Commands actually run, results, uncovered items, and residual risk |
How the customer uses it
Provide at least the codebase path. Optionally provide: target branch/commit, production deployment method, tech stack, threat focus, approved local scanners, test commands, report save location, and acceptable remediation window.
使用 soia-safe-audit-fix-codebase 审计 <repo-path>。
第一阶段只读，给我整体报告和分批修复方案；我确认具体批次后再改代码和测试。
Even if the customer's first sentence says "audit and remediate", the first phase must still be completed and stop at the confirmation gate; code must not be modified directly in the same phase.
Dependencies and installation
Install this skill and its same-repository dependencies:
npx skills add soia-team/soia-open-safe-skills -g -a '*' -s soia-safe-audit-fix-codebase -y
| Dependency | Type | Install / configure | What to do if missing |
|---|---|---|---|
soia-dev-fix-loop |
Hard dependency (dev-coding repository) | npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-fix-loop -y |
Audit can continue; the remediation phase stops, and a simplified hand-written loop must not be used |
soia-dev-coding-protocol |
Hard dependency (dev-coding repository) | npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-coding-protocol -y |
The remediation phase stops to avoid lack of verification or scope expansion |
soia-safe-track-vulnerability-intel |
Optional enhancement | Installed with this repository | Code auditing can still be done, but dependency intelligence coverage is marked as degraded |
| Project-native build/test tools | Hard dependency for verification | Install according to repository documentation | Can only report unverified remediation, and must not be called passed |
| SAST/SCA/SBOM tools | Optional enhancement | Use local tools already approved by the customer | Degrade using native dependency trees, lock files, and manual auditing, and list the gaps |
This skill does not require private configuration by default. Tool preferences can be placed in:
~/.config/soia-skills/soia-safe-audit-fix-codebase/config.yml
SOIA_SAFE_AUDIT_CODEBASE_CONFIG_FILE=<custom-config-path>
Tokens, private keys, cookies, database connection strings, source code bodies, or production data must not be stored in configuration, reports, or logs.
Logging and completion receipts
The audit phase reports the scope read, exclusions, language/build system, dependencies and entry point counts, scanners actually run, number of Findings, false-positive review, coverage gaps, and whether the code tree has changed.
The remediation phase reports per Finding fix/reject/defer, modified files, tests, rescans, independent review, and residual risk. Commit, push, PR, deployment, and release are not included in remediation authorization and require separate explicit authorization.
Confirmation gates that must not be crossed
Phase A is a read-only audit; only Phase B may make modifications. Full rules see confirmation gate contract。
At the end of Phase A, the following must be provided:
- Audit baseline: generalized identifier of the repository path, branch/commit, working tree status;
- Finding table: stable ID, severity,
file:line, evidence, impact, and confidence; - Remediation batch: which Findings are included, which files are planned to be modified, behavior changes, tests, rollback, and risk;
- Explicit request: ask the client to confirm one or more batches/IDs.
Valid confirmation examples:
确认修复批次 B1，包含 F-001、F-003；允许修改列出的 4 个文件并运行报告中的测试。
If the code, branch, commit, working tree, or remediation scope changes materially after confirmation, the original confirmation is invalidated; regenerate the affected batches and confirm again.
Phase A: Read-only project security audit
1. Freeze scope and scene
Resolve the target path and confirm it is the expected repository. Read the root directory and relevant subdirectories' AGENTS.md, contribution guidelines, security policy, build and test instructions. Record the Git branch, commit, and existing uncommitted changes; do not clean, overwrite, stage, or modify client changes.
Define what the audit includes and excludes. For example: source code, dependencies, containers/IaC, CI/CD, configuration samples, authentication boundaries; exclude third-party vendored code, generated directories, binaries, and real secret files. When encountering symlinks, submodules, and multi-repo directories, explicitly list the boundaries.
2. Build the project inventory
Run a read-only inventory:
python3 scripts/inventory_codebase.py <repo-path>
The script only outputs languages, manifest files, build entry points, containers/IaC, and test clues; it does not read or upload secret content. The inventory result is only navigation, not a security conclusion.
3. Build the attack surface and data flows
Identify external entry points, trust boundaries, identities and permissions, data storage, external calls, deserialization, file handling, command execution, background tasks, admin endpoints, and deployment boundaries. Prioritize reviewing high-risk data flows; do not expend equal effort on all files.
Read by tech stack security audit checklist, and apply only the relevant items. For framework or library behavior, consult official documentation, source code, or locked versions; do not assert from memory.
4. Audit dependencies and known vulnerabilities
Check direct dependencies, transitive dependencies, lock files, final JAR/WAR/binaries, container images, and SBOM. If soia-safe-track-vulnerability-intel is available, pass in exact package names, versions, PURL/CPE, and deployment conditions for correlation; otherwise use the project's native dependency tree and an approved local SCA, and mark intelligence coverage as degraded in the report.
The presence of a dependency does not equal exploitability. List evidence separately for version matches, call reachability, configuration, deployment method, and external exposure.
5. Form and adversarially review Findings
Each Finding must include:
- stable ID, severity, and confidence;
file:lineor dependency/artifact location;- observable dangerous behavior and the preconditions required by the attacker;
- Impact scope and affected assets;
- Minimal safe reproduction or static evidence;
- Remediation direction, testing recommendations, and sources.
Before reporting, attempt to disprove each finding: check whether the input is truly controllable, whether the dangerous path is reachable, whether the framework already has encoding/validation, and whether deployment meets the conditions. When it cannot be proven, lower the confidence or list it as "to be confirmed"; do not pass off scanner titles as facts.
6. Output the report and remediation preview, then stop
Follow Project Security Report Contract to output the management summary, architecture and attack surface, Findings, dependency risks, coverage gaps, and remediation batches.
After confirming the following facts, end Phase A:
- No code was modified, formatted, generated, or deleted;
- No commands were run that could change dependency locks, databases, remote or production state;
- The customer has seen the remediation files, behavior changes, tests, and rollback preview;
- It has been made clear that confirmation is awaited, and Phase B has not yet begun.
Phase B: Post-confirmation remediation and verification
1. Re-check confirmation and baseline
Only handle the Finding/batch confirmed by the customer. Re-read the branch, commit, working tree, and target files; if drift is found, stop and refresh the preview. Existing unrelated changes must be preserved and must not be included in the patch.
2. Establish safe reproduction
Prefer unit tests, integration fixtures, static assertions, or local canaries. Do not execute PoCs, port scans, brute force, real command execution, data exfiltration, or destructive verification in the production environment. If safe reproduction is not possible, state the reason and alternative evidence.
3. Invoke the remediation closed loop
Hand the confirmed Findings to soia-dev-fix-loop, and follow soia-dev-coding-protocol: select item by item fix/reject/defer, implement the minimal remediation, search for similar patterns, and do not fake remediation with TODOs, swallowed errors, disabled rules, lowered assertions, or deleted tests.
If the remediation scope expands to new files, public APIs, databases, authentication models, or deployment architecture, first update the batch and reconfirm.
4. Layered verification
Each fix must at least have:
- Direct verification: the original dangerous behavior no longer holds;
- Normal path: legitimate input and business behavior still hold;
- Related regression: caller, module, or service tests;
- Rescan: the original rule/SCA/SAST no longer triggers, and it is not ignored;
- Independent review: inspect the diff, counterexample inputs, downstream calls, or another review perspective.
When test tools cannot run, the environment is incomplete, or the cost of full regression has not been authorized, the conclusion can only be "partially verified" or "blocked", and cannot be called a passing test.
5. Deliver the remediation receipt
List the decisions, code changes, direct tests, regression, rescan, independent review, and residual risk by Finding. Check the working tree to confirm that unauthorized files have not been mixed in.
Commit, push, PR creation, merge, deployment, or release all require separate authorization; "confirm remediation" only authorizes local modifications and the tests listed in the preview.
Private information and intermediate data
- By default, the audit runs entirely locally and does not upload source code, artifacts, SBOMs, paths, dependency manifests, or reports to third-party AI/scanning services.
- If a cloud scanner is needed, the fields sent, target service, and retention policy must first be explained, and customer authorization must be obtained.
- Reports remain in the session by default; when saving, use the directory selected by the customer. Intermediate data uses the OS temporary directory and is cleaned up after success or failure.
- Logs and reports are redacted for tokens, private keys, passwords, connection strings, cookies, internal hostnames, user data, and absolute paths; evidence retains only the minimal fragments needed for locating.
Resources
- Project read-only inventory:
scripts/inventory_codebase.py - Audit perspective:references/audit-checklist.md
- Report structure:references/report-contract.md
- Confirmation and authorization:references/confirmation-gate.md
Verification
python3 scripts/inventory_codebase.py --self-test
python3 scripts/inventory_codebase.py <repo-path> --pretty
The real forward test uses a temporary fixture repository: place source code, manifest, tests, CI, container files, ignored directories, and a secret candidate identified only by name; after running the inventory, verify that the target tree is unchanged, ignored directories are not included in the statistics, and secret contents and absolute paths do not appear in the JSON. Do not enter Phase B on a real production repository for the purpose of testing this skill.
The skill itself must also verify: the target repository diff/status is consistent before and after Phase A; Phase B produces a diff only after valid confirmation; every fixed Finding has a direct test and at least one independent review evidence item.