Container Security Audit

0. Mandatory reading contract

You MUST read this entire SKILL.md before executing an audit or making container-security changes.

Then load the relevant supporting files:

• references/tooling.md — tools, installation, commands, scan modes
• references/cve-triage.md — interpreting and prioritizing CVEs
• references/container-hardening.md — Dockerfile/image/runtime hardening
• references/build-host-security.md — builder/host/Docker-daemon risk
• references/ci-and-automation.md — CI gates and repeatable workflows
• templates/audit-report.md — mandatory report format

Do not skip a relevant reference merely because you think you already know the topic.

This skill is designed for any project that builds Docker/OCI images. It must remain language- and framework-agnostic.

1. Objective

Given a source repository:

1. discover container build/deployment structure;
2. identify relevant Dockerfiles/images;
3. inspect local project configuration;
4. scan repository, secrets, misconfigurations, and dependencies;
5. build the relevant image(s) when safe and possible;
6. scan the built image(s);
7. triage serious findings;
8. apply safe, source-controlled remediations;
9. rebuild;
10. rescan;
11. verify application behavior using existing project checks;
12. create a timestamped Markdown audit report in the project;
13. if repository files changed, generate a strict Conventional Commit message.

Expected lifecycle:

discover
  ↓
inspect
  ↓
scan source/config
  ↓
build image
  ↓
scan image
  ↓
triage
  ↓
remediate
  ↓
rebuild
  ↓
rescan
  ↓
verify
  ↓
report
  ↓
suggest commit message

2. Scope

This skill covers:

• Dockerfiles and OCI-compatible image builds
• base-image review
• OS and application package vulnerabilities
• image vulnerability scanning
• filesystem/repository scanning
• secret detection
• Dockerfile/build misconfiguration checks
• SBOM generation when justified
• CVE triage
• runtime-user and privilege review
• build-host risk review
• local developer workflows
• optional CI integration
• remediation and verification
• timestamped audit reports
• Conventional Commit output when files change

This skill does NOT replace:

• SAST
• DAST
• penetration testing
• runtime IDS/EDR
• Kubernetes cluster security reviews
• host OS hardening
• cloud IAM reviews
• business-logic security reviews
• full threat modeling

A clean container scan does not prove the application is secure.

References

• NIST SP 800-190: https://csrc.nist.gov/pubs/sp/800/190/final
• OWASP Docker Security Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html

3. Operating principles

3.1 Scanner output is evidence, not truth

A scanner match means a component/version appears associated with a known issue.

It does not automatically prove:

• the vulnerable code path is reachable;
• the issue applies to the specific distro build;
• the package is used at runtime;
• exploitation is practical in this deployment.

Investigate serious findings.

3.2 Never optimize for "zero findings"

Do not:

• remove required functionality just to reduce counts;
• suppress findings without justification;
• downgrade software to silence a scanner;
• swap base image families solely because another image has fewer CVEs;
• hide unfixed vulnerabilities and call the image clean.

3.3 Prefer source-controlled remediation

Prefer:

Dockerfile/dependency change
          ↓
rebuild
          ↓
rescan

over patching a production image in place.

3.4 Preserve behavior

Security changes must not silently break:

• startup
• native dependencies
• filesystem permissions
• TLS certificates
• timezone behavior
• signal handling
• networking
• writable directories
• runtime users

3.5 Keep security data current

Commands, image tags, tool behavior, and CVE state may change.

Before relying on time-sensitive details, consult current primary documentation.

Source priority:

1. vendor/project security advisory
2. OS/distribution advisory
3. tool maintainer docs
4. Docker docs
5. NIST/CISA/NVD
6. FIRST EPSS when useful
7. cloud-provider security guidance
8. OWASP
9. reputable security research
10. community material only as supplemental evidence

If current web access is unavailable, use installed tool --help/version output and clearly document the limitation.

4. Audit modes

Default mode: STANDARD

QUICK

Use for fast developer checks:

• project discovery
• Docker build checks if supported
• focused repository scan
• local image build
• HIGH/CRITICAL image scan
• minimal triage
• mandatory report

STANDARD

Use by default:

• full project discovery
• tool/version discovery
• Dockerfile/build checks
• repository vulnerability scan
• secret scan
• misconfiguration scan
• image build
• full image vulnerability scan
• HIGH/CRITICAL actionable view
• base-image review
• runtime-user/privilege review
• build-host risk review
• safe remediation
• rebuild
• rescan
• project verification
• mandatory report
• Conventional Commit suggestion if files changed

DEEP

STANDARD plus, when justified:

• SBOM generation
• second scanner
• detailed dependency-origin analysis
• base-image alternative analysis
• deeper build-host review
• KEV/EPSS prioritization
• waiver review
• CI security-gate recommendations

DEEP means deeper investigation, not more aggressive modification.

5. Phase A — project discovery

Before editing or building, inspect:

Dockerfile
Dockerfile.*
**/Dockerfile
compose.yml
compose.yaml
docker-compose.yml
docker-compose.yaml
.dockerignore
.github/workflows/
.gitlab-ci.yml
Jenkinsfile
Procfile
Makefile
Taskfile*
scripts/
docs/
security/
package manifests
lockfiles
deployment files

Also read repository-local instructions if present:

AGENTS.md
CONTRIBUTING.md
README.md

Detect:

• container runtime
• Dockerfile path(s)
• build context(s)
• multi-stage vs single-stage
• base image(s)
• package ecosystem(s)
• package manager(s)
• runtime user
• exposed ports
• CI provider
• deployment model
• whether production builds source directly
• whether multiple deployable images exist

If multiple production-relevant images exist, audit each relevant image.

Never assume Node.js, Python, Go, Rust, Java, PHP, .NET, Ruby, etc. until discovered.

6. Phase B — choose tools and read relevant references

Before running scans, read:

references/tooling.md

For serious CVEs, also read:

references/cve-triage.md

For Dockerfile/runtime findings, also read:

references/container-hardening.md

If builds occur on production, Docker socket access exists, or builder isolation matters, read:

references/build-host-security.md

If CI integration or repeatable local automation is requested, read:

references/ci-and-automation.md

Default scanner: Trivy

Optional supporting tools:

• Docker Build checks
• Syft
• Grype

Do not run every tool simply because it exists.

7. Phase C — baseline scans

Use the exact commands appropriate to the installed versions.

Typical STANDARD sequence:

docker version
docker buildx version
trivy --version

When supported:

docker build --check .

Repository scan:

trivy fs --scanners vuln,misconfig,secret .

Do not print full discovered secrets into chat, logs, or reports.

If a real credential is discovered, remember:

delete from file
≠
credential fixed

Potential remediation:

revoke
  ↓
rotate
  ↓
remove from source/build context
  ↓
consider history cleanup
  ↓
replace with supported secret mechanism

8. Phase D — build audit image

Use a clearly temporary/local image tag, for example:

docker build -t <project>:security-audit .

If testing whether current base-image updates remediate findings:

docker build --pull -t <project>:security-audit .

Do not use --no-cache unless there is a reason.

Never inject real secrets into insecure Docker ARG/ENV merely to make a build succeed.

Before building an unfamiliar Dockerfile, inspect:

• RUN commands
• remote downloads
• build scripts
• unusual mounts
• BuildKit insecure entitlements
• Docker socket exposure
• host path mounts

A Docker build executes build instructions. It is not harmless static analysis.

9. Phase E — scan image

First run the full scan:

trivy image <project>:security-audit

Then focused serious findings:

trivy image --severity HIGH,CRITICAL <project>:security-audit

Optionally show currently fixable serious findings:

trivy image --severity HIGH,CRITICAL --ignore-unfixed <project>:security-audit

Interpret --ignore-unfixed only as an actionable view.

Do NOT use it to claim the image has no remaining risk.

For machine-readable investigation when necessary:

trivy image --format json --output <temporary-path>/trivy-image.json <image>

Do not commit raw scanner output by default.

10. Phase F — triage

For meaningful HIGH/CRITICAL findings, read:

references/cve-triage.md

Collect, where available:

CVE/advisory ID
package
installed version
fixed version
severity
severity source
OS vs application dependency
direct vs transitive
build-time vs runtime
fix available?
vendor/distribution status
KEV status if checked
EPSS context if useful
likely reachable/exposed?
recommended remediation
confidence

Disposition must be one of:

ACTION NOW
ACTION WHEN FIX AVAILABLE
ACCEPT TEMPORARILY WITH JUSTIFICATION
NOT APPLICABLE WITH EVIDENCE
FALSE POSITIVE WITH EVIDENCE
NEEDS MANUAL REVIEW

Never use "ignore" as analysis.

11. Phase G — hardening review

Read:

references/container-hardening.md

Review:

• base-image maintenance/support status
• tag/digest strategy
• multi-stage build opportunities
• unnecessary runtime packages
• root vs non-root runtime
• .dockerignore
• overly broad COPY
• secret handling
• package-manager residue
• remote download integrity
• entrypoint/CMD behavior
• health check relevance
• privileged mode
• Linux capabilities
• host mounts
• Docker socket mounts
• writable root filesystem
• EOL distro/runtime

Classify each finding as:

SECURITY ISSUE
HARDENING OPPORTUNITY
RELIABILITY ISSUE
MAINTAINABILITY ISSUE
INFORMATIONAL

Do not call every style issue a vulnerability.

12. Phase H — build-host review

If relevant, read:

references/build-host-security.md

Explicitly distinguish:

image security

from:

machine that builds/runs the image

If production also builds source, document:

build/runtime isolation: shared host

Do not automatically:

• migrate production to rootless Docker
• reconfigure daemon settings
• change firewall rules
• change kernel security settings
• stop Docker
• restructure CI
• alter Dokku/Dokploy internals

Host hardening requires its own explicit workflow/approval.

13. Phase I — remediation hierarchy

Prefer, where applicable:

1. update vulnerable direct dependency
2. update vulnerable transitive dependency via supported resolution
3. refresh base image
4. update to maintained base-image release
5. remove unnecessary vulnerable runtime package
6. move build-only packages into builder stage
7. harden Dockerfile safely
8. change base-image family only when justified and tested
9. document unresolved upstream issues
10. create a time-bounded waiver only when remediation is not currently appropriate

Do not:

• mass-upgrade unrelated packages without reason
• add blanket OS upgrades only to manipulate scan counts
• switch to Alpine/distroless solely for lower CVE counts
• break compatibility to make the scanner green

14. Phase J — rebuild, rescan, verify

A remediation is incomplete until verified.

Mandatory loop:

baseline
  ↓
change
  ↓
rebuild
  ↓
rescan
  ↓
test
  ↓
compare

Rebuild the relevant image.

If base-image freshness is part of the fix:

docker build --pull -t <project>:security-audit .

Rescan:

trivy image <project>:security-audit
trivy image --severity HIGH,CRITICAL <project>:security-audit

Run existing project checks where available:

• unit tests
• integration tests
• typecheck
• lint
• smoke test
• container startup
• health endpoint
• application-specific validation

Do not fabricate successful verification.

If something cannot be verified, report that explicitly.

15. Mandatory audit report

Every completed audit MUST create a Markdown report.

Read and use:

templates/audit-report.md

Preferred location order:

existing project security/docs convention
→ docs/security/audits/

If no relevant directory exists, create:

docs/security/audits/

Filename:

container-security-audit-YYYYMMDD-HHmmssZ.md

Use UTC.

Example:

docs/security/audits/container-security-audit-20260930-112300Z.md

Reports must never contain raw secrets.

If something was not checked, write:

Not checked

not:

No issue

If a scan failed, document the failure.

16. Conventional Commit requirement

If repository files changed, generate a commit message strictly following Conventional Commits 1.0.0.

Default security-fix form:

fix(security): remediate container audit findings

Prefer precision:

fix(security): update runtime base image and drop root user

Dependency-only remediation:

fix(deps): update vulnerable runtime dependencies

Report-only change:

docs(security): add container security audit report

Breaking changes:

fix(security)!: harden container runtime contract

BREAKING CHANGE: <explanation>

Do not run git commit unless explicitly authorized.

Reference

• Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/

17. Waiver rules

Suppressions require evidence.

A waiver should include:

id: CVE-YYYY-NNNN
package: example
status: accepted-temporarily
reason: "..."
evidence: "..."
reviewed_at: YYYY-MM-DD
expires_at: YYYY-MM-DD
owner: project-team

Rules:

• every suppression has a reason
• every suppression has a review date
• temporary suppressions have an expiry
• never suppress solely to make CI green
• reevaluate when vendor/scanner data changes

If using Trivy ignore/VEX features, verify current official syntax first.

18. CI and local automation

CI is optional.

The audit must work locally without:

• GCR
• ECR
• GHCR
• Docker Hub push
• paid security SaaS
• paid runners

A valid CI flow is:

checkout
  ↓
build temporary image
  ↓
scan
  ↓
pass/fail
  ↓
discard image

No registry required.

For implementation guidance, read:

references/ci-and-automation.md

19. User-visible execution behavior

During an audit:

1. state which Dockerfiles/images were discovered;
2. surface serious confirmed issues early;
3. explain why each remediation is being applied;
4. avoid dumping hundreds of low-value findings;
5. report before/after counts;
6. identify changed files;
7. give the audit report path;
8. give the Conventional Commit message if files changed.

20. Default STANDARD checklist

Discovery

• read this full SKILL.md
• read repository-local instructions
• inspect git status
• do not overwrite unrelated changes
• locate all Dockerfiles
• locate Compose/deployment files
• locate .dockerignore
• detect package ecosystems/lockfiles
• detect CI/deployment model
• identify production-relevant images
• identify whether production builds source

Tools

• read references/tooling.md
• record Docker version
• record Buildx version
• record Trivy version
• record Syft/Grype only if used
• verify current docs for version-sensitive behavior

Baseline

• run Docker build checks where supported
• run repository vuln/misconfig/secret scan
• build local audit image
• run full image scan
• run HIGH/CRITICAL view

Analysis

• triage serious CVEs
• read references/cve-triage.md
• review Dockerfile/runtime hardening
• read references/container-hardening.md
• review build-host isolation where relevant
• read references/build-host-security.md

Remediation

• apply only justified changes
• preserve application behavior
• avoid unrelated cleanup
• document waivers when needed

Verification

• rebuild
• rescan
• run existing project verification
• compare before/after

Reporting

• read templates/audit-report.md
• create timestamped report
• redact all secrets
• include actual sources used
• generate strict Conventional Commit if files changed
• do not auto-commit unless authorized

21. Definition of done

An audit is complete only when:

• relevant build surfaces were discovered
• tools/versions were recorded
• repository/configuration checks were run where possible
• relevant images were built or inability was documented
• relevant images were scanned
• serious findings were triaged
• safe remediation was applied where justified
• remediated images were rebuilt
• remediated images were rescanned
• available tests/checks were run
• unresolved risk was documented
• no secrets were leaked into reports
• timestamped audit report was created
• report includes actual sources consulted
• Conventional Commit was generated if repository files changed
• no automatic commit occurred without authorization

22. Final rule

Do not confuse:

scanner clean

with:

secure

The objective is:

know what is present
+
know what is vulnerable
+
understand what is relevant
+
fix what can safely be fixed
+
document what remains
+
make the process reproducible