Execute a security loop of "audit first, confirm next, remediate last" on a complete codebase. The first run may 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 | Exact 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-skills -g -a '*' -s soia-safe-audit-fix-codebase -y
| Dependency | Type | Installation / configuration | What to do if missing |
|---|---|---|---|
soia-dev-fix-loop |
Hard dependency | Installed with this repository | Audit may continue; the remediation phase stops, and a simplified handwritten loop must not be used |
soia-dev-coding-protocol |
Hard dependency | Installed with this repository | 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 to 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-open-skills/soia-safe/soia-safe-audit-fix-codebase/config.yml
SOIA_SEC_AUDIT_CODEBASE_CONFIG_FILE=<custom-config-path>
Do not store tokens, private keys, cookies, database connection strings, source code bodies, or production data in configurations, reports, or logs.
Logs and completion receipts
The audit phase reports the read scope, exclusion scope, language/build system, number of dependencies and entry points, scanners actually run, number of findings, false-positive verification, coverage gaps, and whether the code tree has changed.
The remediation phase reports by finding fix/reject/defer, modified files, tests, rescans, independent review, and residual risk. Commits, pushes, PRs, deployments, and releases 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. For complete rules, see confirmation gate contract。
At the end of Phase A, the following must be provided:
- Audit baseline: a generalized identifier for the repository path, branch/commit, and working tree status;
- Finding table: stable ID, severity,
file:line, evidence, impact, and confidence; - Remediation batch: which findings are included, which files are planned for modification, behavior changes, tests, rollback, and risks;
- Explicit question: request that the customer confirm one or more batches/IDs.
Examples of valid confirmation:
确认修复批次 B1，包含 F-001、F-003；允许修改列出的 4 个文件并运行报告中的测试。
If the code, branch, commit, working tree, or remediation scope changes materially after confirmation, the original confirmation becomes invalid; regenerate the affected batches and confirm again.
Phase A: Read-only project security audit
1. Freeze scope and site
Resolve the target path and confirm it is the expected repository. Read the root directory and relevant subdirectories for the AGENTS.md, contribution guidelines, security policy, and build and test instructions. Record the Git branch, commit, and existing uncommitted changes; do not clean, overwrite, stage, or modify customer 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 a project inventory
Run a read-only inventory:
python3 scripts/inventory_codebase.py <repo-path>
The script outputs only languages, manifest files, build entry points, containers/IaC, and test clues, and does not read or upload secret content. Inventory results are only navigation, not security conclusions.
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 review of high-risk data flows and do not apply equal effort to all files.
Read by technology stack security audit checklist, and apply only relevant items. The behavior of frameworks or libraries must be checked against official documentation, source code, or locked versions, and must not be asserted from memory.
4. Audit dependencies and known vulnerabilities
Check direct dependencies, transitive dependencies, lock files, final JAR/WAR/binaries, container images, and SBOMs. 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 approved local SCA, and mark intelligence coverage degradation in the report.
The existence of a dependency does not mean it is exploitable. 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 identifier, severity, and confidence;
file:lineor dependency/artifact location;- observable dangerous behavior and the prerequisites required by the attacker;
- impact scope and affected assets;
- minimal safe reproduction or static evidence;
- remediation direction, testing recommendations, and sources.
Before reporting, try to refute each finding: check whether the input is truly controllable, whether the dangerous path is reachable, whether the framework already has encoding/validation, and whether the deployment meets the conditions. If it cannot be proven, downgrade 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
According to Project Security Report Contract output the management summary, architecture and attack surface, Findings, dependency risks, coverage gaps, and remediation batches.
End Phase A after confirming the following facts:
- no code was modified, formatted, generated, or deleted;
- no commands were run that could change dependency locks, databases, remote systems, or production state;
- the customer has seen the remediation files, behavior changes, tests, and rollback preview;
- it is clearly waiting for confirmation and has not yet entered Phase B.
Phase B: Remediation and Verification After Confirmation
1. Recheck confirmation and baseline
Handle only 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 a safe reproduction
Prefer unit tests, integration fixtures, static assertions, or a local canary. Do not execute PoCs, port scans, brute force, real command execution, data exfiltration, or destructive verification in the production environment. If a 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 one by one fix/reject/defer, implement the minimal fix, search for similar patterns, and do not fake a fix 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 have at least:
- direct verification: the original dangerous behavior no longer holds;
- normal path: legitimate input and business behavior still hold;
- related regression: tests for callers, modules, or services;
- rescan: the original rule/SCA/SAST no longer hits, and it is not being ignored;
- independent review: inspect the diff, counterexample inputs, downstream calls, or another review perspective.
When test tools cannot run, the environment is incomplete, or full regression cost is not authorized, the conclusion can only be "partially verified" or "blocked", and cannot be called test passed.
5. Deliver the remediation receipt
List the decisions, code changes, direct tests, regression, rescan, independent review, and residual risks by Finding. Check the working tree to confirm that no unauthorized files were 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
- Audits run locally by default throughout, and do not upload source code, artifacts, SBOMs, paths, dependency manifests, or reports to third-party AI/scanning services.
- When a cloud scanner is required, the fields sent, target services, and retention policy must first be specified, and customer authorization must be obtained.
- Reports remain in the session by default; when saved, use the directory chosen by the customer. Intermediate data uses the OS temporary directory and is cleaned up after success or failure.
- Logs and reports redact Tokens, private keys, passwords, connection strings, Cookies, internal hostnames, user data, and absolute paths; evidence retains only the minimal fragment needed for locating.
Resources
- Read-only project 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
Real forward testing uses a temporary fixture repository: place source code, manifest, tests, CI, container files, an ignored directory, and a secret candidate identified only by name; after running the inventory, verify that the target tree is unchanged, the ignored directory did not enter the statistics, and the secret content and absolute paths did 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; each fixed Finding has a direct test and at least one piece of independent review evidence.