<p>AI coding agents can write code, review PRs, and run tests. They
can't run security scans unless you give them the tools. I built a
Docker image that bundles three scanners into one container, then
wired it into my repo so any AI tool can use them.</p>
<h1 id="whats-in-the-image">What's in the image</h1>
<p>The image <code>kpericak/ai-security-toolkit-1</code> has 3 tools:</p>
<table>
<thead>
<tr>
<th>Category</th>
<th>Tool</th>
</tr>
</thead>
<tbody>
<tr>
<td>SAST (static analysis)</td>
<td><a href="https://semgrep.dev/">semgrep</a></td>
</tr>
<tr>
<td>SCA (dependency vulns)</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
<tr>
<td>Secrets (files on disk)</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
<tr>
<td>Secrets (git history)</td>
<td><a href="https://gitleaks.io/">gitleaks</a></td>
</tr>
<tr>
<td>Misconfig (Dockerfile, Terraform)</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
<tr>
<td>Container image scanning</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
</tbody>
</table>
<h1 id="the-dockerfile">The Dockerfile</h1>
<p>Multi-stage build. Copy the Go binaries from the official images,
install semgrep via pip on Alpine.</p>
<pre><code class="language-dockerfile">FROM aquasec/trivy:0.69.3 AS trivy
FROM zricethezav/gitleaks:v8.30.0 AS gitleaks

FROM python:3.12.13-alpine

RUN apk upgrade --no-cache &#x26;&#x26; apk add --no-cache nodejs git gcc musl-dev

COPY --from=trivy /usr/local/bin/trivy /usr/local/bin/trivy
COPY --from=gitleaks /usr/bin/gitleaks /usr/local/bin/gitleaks

RUN pip install --no-cache-dir semgrep

COPY .trivyignore /workspace/.trivyignore

RUN addgroup -S scanner &#x26;&#x26; adduser -S scanner -G scanner
RUN mkdir -p /workspace &#x26;&#x26; chown scanner:scanner /workspace

WORKDIR /workspace
USER scanner
ENTRYPOINT ["/bin/sh"]
</code></pre>
<p>Trivy and gitleaks are single Go binaries, so the COPY stages are all they need.
Semgrep needs Python and a C compiler for its native
extensions, which is why <code>gcc</code> and <code>musl-dev</code> are there. The base
images are pinned to specific versions for reproducible builds. A
non-root <code>scanner</code> user runs the tools so the container doesn't
operate as root. The image ends up around 800MB. Not small, but
it's a tooling image, not a production service.</p>
<p>Source:
<a href="https://github.com/kylep/multi/tree/main/infra/ai-security-toolkit-1">GitHub</a></p>
<h1 id="teaching-ai-agents-to-scan">Teaching AI agents to scan</h1>
<p>The scans are just shell commands. The objective is getting robot to run them.
I use <a href="/ruler-cross-tool-ai-rules.html">Ruler</a> to maintain a single
<code>.ruler/security.md</code> file that gets injected into CLAUDE.md,
AGENTS.md, and any other tool-specific config.</p>
<p>Here's the ruler file:</p>
<pre><code class="language-markdown"># Security Scanning

The Docker image `kpericak/ai-security-toolkit-1:0.2` bundles
semgrep, trivy, and gitleaks in one Alpine container.

Run from the repo root. Mount the project directory as /workspace.

## Static analysis (semgrep)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "semgrep scan --config auto /workspace"

## Vulnerability scanning (trivy)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "trivy fs --scanners vuln,secret,misconfig /workspace"

## Container image scanning (trivy)
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "trivy image &#x3C;image:tag>"

## Secret scanning (gitleaks)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "cd /workspace &#x26;&#x26; gitleaks detect --source ."
</code></pre>
<p>After running <code>ruler apply</code>, every AI tool in the repo knows how to
run security scans. I can tell Claude Code "scan this repo for
vulnerabilities" and it has the commands ready.</p>
<h1 id="pre-commit-hooks">Pre-commit hooks</h1>
<p>Both semgrep and gitleaks run as
<a href="https://pre-commit.com/">pre-commit</a> hooks. Every commit gets
a static analysis scan and a secret scan before it lands.</p>
<h2 id="installing-pre-commit">Installing pre-commit</h2>
<p>You need <a href="https://pre-commit.com/">pre-commit</a> installed, plus
Docker for the scanner container.</p>
<pre><code class="language-bash"># macOS
brew install pre-commit

# Linux (pip)
pip install pre-commit

# Then activate hooks in the repo
cd your-repo
pre-commit install
</code></pre>
<p>That wires <code>.pre-commit-config.yaml</code> into <code>.git/hooks/pre-commit</code>
so the hooks run automatically on every commit.</p>
<h2 id="the-hook-config">The hook config</h2>
<pre><code class="language-yaml">- id: semgrep
  name: Semgrep
  description: Static analysis scan using the security toolkit image.
  entry: bash -c 'docker run -v "$(pwd):/workspace:ro" --rm
    kpericak/ai-security-toolkit-1:0.2
    -c "semgrep scan --config auto --error /workspace"'
  language: system
  stages: ["pre-commit", "pre-push"]
- repo: https://github.com/gitleaks/gitleaks
  rev: v8.30.0
  hooks:
    - id: gitleaks
      stages: ["pre-commit", "pre-push"]
</code></pre>
<p>The <code>--error</code> flag on semgrep makes it exit non-zero on findings,
which blocks the commit. Gitleaks uses its official pre-commit
hook, which pre-commit installs via Go. It scans staged files
directly. Use <code>gitleaks detect</code> for full repo scans.</p>
<h1 id="running-the-scans">Running the scans</h1>
<p>Here's what each scanner produces when pointed at this monorepo.</p>
<h2 id="semgrep">semgrep</h2>
<p>The first scan found 43 findings. Most were false positives:
<code>dangerouslySetInnerHTML</code> in the blog's SSG rendering (the HTML
comes from my own markdown), <code>path.join</code> with internal filenames,
K8s manifests in old sample projects, and vendored Prism.js.</p>
<p>Two changes got it to zero:</p>
<ol>
<li>A <code>.semgrepignore</code> file to skip directories that aren't active
code: <code>samples/</code>, old infra, vendored JS, and a legacy project.</li>
<li>Inline <code>// nosemgrep</code> comments on the few remaining lines where
the finding is a known false positive, like the SSG innerHTML.</li>
</ol>
<pre><code>┌──────────────┐
│ Scan Summary │
└──────────────┘
Ran 717 rules on 485 files: 0 findings.
</code></pre>
<p>Zero findings means semgrep can run as a pre-commit hook with
<code>--error</code> and block on any new issue. No triage fatigue.</p>
<h2 id="trivy">trivy</h2>
<p>Trivy's default scanners are <code>vuln</code> and <code>secret</code>. It also has
<code>misconfig</code> and <code>license</code> scanners. Adding <code>--scanners vuln,secret,misconfig</code> enables Dockerfile and Terraform
misconfiguration checks on top of the dependency and secret
scanning.</p>
<p>The first scan found 7 npm vulnerabilities. 3 HIGH in Next.js
14 (DoS in server components), plus medium/low hits in
dompurify, lodash-es, and diff. I bumped Next.js from 14 to 15
and ran <code>npm audit fix</code> for the transitive deps. The upgrade
required no code changes. Pages Router, <code>output: 'export'</code>, and
React 18 all still work on Next.js 15.</p>
<p>With misconfig enabled, trivy also flagged Dockerfile issues:
no non-root USER, <code>cd</code> instead of <code>WORKDIR</code>, missing
HEALTHCHECK. The kind of things you'd catch in a code review
but might miss if nobody's looking.</p>
<pre><code>Report Summary
┌────────────────────────────────────────┬────────────┬───────┬─────────┬───────────────────┐
│                 Target                 │    Type    │ Vulns │ Secrets │ Misconfigurations │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ apps/blog/blog/package-lock.json       │    npm     │   0   │    -    │         -         │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ apps/blog/Dockerfile                   │ dockerfile │   -   │    -    │         3         │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ apps/blog/tf                           │ terraform  │   -   │    -    │         0         │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ infra/ai-security-toolkit-1/Dockerfile │ dockerfile │   -   │    -    │         1         │
└────────────────────────────────────────┴────────────┴───────┴─────────┴───────────────────┘
</code></pre>
<p>Zero dependency vulns. The Dockerfile misconfigs are real
findings to fix next. The policy going forward: keep SCA vulns
at 0 in active projects. Major package upgrades are acceptable
to get there. Playwright tests catch regressions from the
upgrades.</p>
<h2 id="trivy-image">trivy image</h2>
<p><code>trivy fs</code> scans source code and lock files. <code>trivy image</code>
scans a built Docker image, catching OS-level CVEs in the base
image and vulnerabilities in installed packages that don't show
up in any lock file.</p>
<p>Running it against the first version of the toolkit image found
25 vulnerabilities that <code>trivy fs</code> never saw: Alpine OS
packages, Python dependencies, and Go stdlib CVEs baked into
the trivy and gitleaks binaries.</p>
<p>Fixes for v0.2:</p>
<ol>
<li>Pinned <code>python:3.12.13-alpine</code> and added <code>apk upgrade</code> to
get the latest Alpine packages. Fixed the CRITICAL zlib CVE.</li>
<li>The Go stdlib CVEs live inside the gitleaks binary, compiled
with Go 1.25.4. No newer gitleaks release exists. Added a
<code>.trivyignore</code> with comments explaining each suppression.</li>
</ol>
<p>The policy: no HIGH or CRITICAL findings. MEDIUM and below from
upstream binaries we don't compile are accepted and documented.</p>
<h2 id="gitleaks">gitleaks</h2>
<pre><code>144 commits scanned.
no leaks found.
</code></pre>
<p>Clean. Gitleaks scans git history by default, so it catches
secrets that were committed and later deleted. Trivy also has
a secret scanner, but it only checks files on disk. If someone
committed an API key and removed it in the next commit, trivy
wouldn't see it. Gitleaks would, because the key is still in
the git log.</p>
<p>That's why both are in the image. Trivy covers dependency vulns
and current-file secrets. Gitleaks covers the git history angle.
I originally had <code>npm audit</code> in the image too, but dropped it
since trivy already scans <code>package-lock.json</code> for the same CVEs.</p>
<h1 id="the-workflow">The workflow</h1>
<p>With all this wired up, security scanning happens at three levels:</p>
<ol>
<li><strong>Every commit</strong>: semgrep and gitleaks run as pre-commit hooks.
Any new static analysis finding or leaked secret blocks the
commit.</li>
<li><strong>Scheduled</strong>: a security agent runs <code>trivy image</code> against
built container images on a schedule, triages the results,
and files issues in
<a href="/linear-mcp.html">Linear</a> for anything that needs attention.
Image scanning is too slow for pre-commit hooks but catches
OS-level CVEs that filesystem scans miss.</li>
<li><strong>On demand</strong>: I tell the AI agent "run security scans" or
include it in task instructions. The agent runs the docker
commands from its CLAUDE.md context and triages the output.</li>
</ol>
<p>The AI agent is good at triaging scan results. It can reason about
which dependency vulnerabilities actually matter for a static
export vs a running server. That's the real value of combining
scanners with AI agents: the agent reads the output instead of
just dumping a report.</p>


Kyle Pericak

"It works in my environment"

Categories

Tags