DockSec Unpacked: How a Four-Stage Pipeline Is Rewiring Container Security

Container security has long struggled to bridge the gap between detecting vulnerabilities and actually fixing them. A new technical deep-dive into DockSec reveals an architecture designed to close that gap through a composable four-stage pipeline and a single shared data contract that ties every component together.

Published July 14, 2026 by Advait Patel on SecureWorld, the second installment of the DockSec Series pulls back the curtain on how the tool transforms raw scan data into actionable security intelligence — across multiple output formats, AI providers, and deployment environments — without multiplying complexity at every turn.

---

A Pipeline Built for Clarity, Not Chaos

At its core, DockSec runs four sequential stages: scan, analyze, recommend, and report. Three established tools handle the scanning locally — Trivy for known CVEs across OS and language packages, Hadolint for Dockerfile best-practice linting, and Docker Scout for base image comparisons and upgrade recommendations.

An LLM pass follows the scan stage, correlating findings and producing structured output against a defined schema. A scoring stage then generates a single 0-100 security posture number. Finally, a reporting stage emits results in whichever formats the user requested — terminal summary, JSON payload, SARIF file, PDF, HTML, or CSV — all from one run.

What prevents this from becoming an unmanageable tangle is a deliberately unglamorous design decision at the center of the entire system.

Why Sequential Staging Matters

The four-stage model isn't merely a tidy abstraction — it enforces a processing discipline that keeps each component's responsibility narrow and testable. When a stage fails, the failure is localized. When a stage is extended, the blast radius of that change is contained. For teams operating under DevOps principles that prioritize fast, reliable feedback loops, this kind of structural clarity has measurable operational value.

---

The Single Results Contract Holding Everything Together

Every component in DockSec reads from and writes to one shared data structure: a results dictionary with an agreed-upon shape. Each vulnerability record inside that dictionary carries a stable set of fields regardless of which scanner produced it — vulnerability ID, target, package name, installed version, severity, title, description, status, CVSS score, and a reference URL.

Trivy findings are normalized into this shape. Docker Compose misconfiguration findings reuse the exact same shape with an added remediation field. Because every downstream component — the scoring calculator, the report generators, the SARIF writer, and the JSON output — consumes this one contract, none of them need to know anything about Trivy's or Hadolint's native formats.

The Practical Value of a Shared Schema

The practical consequence is significant. Adding a new scanner requires only that it emit records in the established shape. The entire reporting and scoring stack then works without modification. This is why DockSec supports five output formats without five times the codebase complexity.

This same principle applies broadly to application security architecture. Teams building layered security tooling — whether for containers or broader application security and website protection strategies — consistently find that a single, well-defined data contract reduces integration debt more effectively than any individual tool choice.

Caching Without Compromising Accuracy

The scanner layer also includes a results cache keyed on image name and requested severity. Repeated scans of the same image at the same severity level return quickly from cache, while a scan at a different severity correctly triggers a fresh run rather than serving stale data. This is a meaningful distinction: caching is applied where it saves time without distorting results, and bypassed precisely where accuracy requires it.

---

How AI Scoring and Honest Exit Codes Change the Equation

The AI Analysis Pass

When an API key and provider are configured, DockSec runs an AI pass that loads the Dockerfile, truncates it to a token-appropriate size, and prompts the configured model to populate a defined schema covering vulnerabilities, best practices, security risks, exposed credentials, and remediation steps. The output is predictable, parseable, and merged back into the shared results dictionary as AI findings.

This structured-output approach — prompting models to populate a defined schema rather than generating free-form prose — is one of the more transferable patterns in DockSec's design. It makes AI findings reliably parseable and mergeable with existing tooling, which matters considerably when AI output needs to feed downstream automation rather than simply inform a human reader.

Provider handling is abstracted behind a single factory function. OpenAI uses JSON mode for structured output. Anthropic, Google, and Ollama use tool-calling, which LangChain selects automatically. Switching providers requires one flag from the user. Newer Claude and Gemini models that no longer accept a temperature parameter are handled transparently inside that single function.

The Local Fallback Path

When no LLM is available — in scan-only mode or with AI scoring disabled — a local deterministic calculator takes over. It produces a weighted blend across three axes:

• Dockerfile quality from lint results
• Vulnerability burden derived from severity-weighted deductions
• Configuration score that directly penalizes concrete misconfigurations

Those misconfigurations include running as root, credential-looking environment variables, unpinned base images, missing health checks, sensitive exposed ports, use of ADD over COPY, and privileged flags.

One hardening decision stands out. Hardcoded credentials now cap the overall score regardless of how the rest of the blend performs. As the article notes, shipping a plaintext secret in a container image is not a middling problem to be averaged away — and the scoring model reflects that directly.

Exit Codes as a Structural Commitment to Honesty

Exit codes follow the same philosophy. A clean run exits 0. A triggered security gate exits 1. A usage error exits 2. A tool or runtime failure — including a failed AI pass — exits 3. A broken pipeline never masquerades as a passing one.

This is worth emphasizing for engineering leads setting CI/CD policy. The convention of distinct, semantically meaningful exit codes allows pipeline tooling to respond differently to a security failure versus a runtime error — a distinction that generic pass/fail implementations routinely collapse. As container workloads increasingly run within serverless and distributed cloud architectures, where failures can be silent and cascading, this kind of explicit signal design becomes operationally critical.

The Reporting Layer

The reporting layer centralizes all output through a single ReportGenerator that runs silently and returns file paths to the CLI. PDF generation routes all text through a sanitizer so that bullets, smart quotes, em dashes, and emoji in vulnerability titles never crash the output. SARIF is opt-in and independent of the standard format bundle because it targets CI and code-scanning pipelines rather than human readers.

Three Design Principles That Define the Architecture

Three principles emerge clearly from DockSec's architecture and are worth naming explicitly:

• Extensibility is local, not systemic. Adding a scanner or output format is a contained change that does not ripple through unrelated components.
• Honesty is structural. The score reflects real findings. Exit codes reflect real outcomes. Neither is softened by averaging or silent failure.
• Control remains with the operator. The provider abstraction and scan-only path let teams decide where their data goes and whether an external model is involved at all.

---

Part 3 of the series promises hands-on scanning of a deliberately vulnerable Dockerfile, an image, and a Compose stack with line-by-line output analysis. New installments publish on Tuesdays.

---

How you can use this information:

• Security and DevOps teams evaluating container scanning tools can use DockSec's single results contract model as a benchmark for assessing whether other tools offer comparable extensibility and format flexibility without architectural sprawl.
• Developers building or integrating AI into security pipelines can apply the structured-output approach — prompting models to populate a defined schema rather than generating free-form prose — to make AI findings reliably parseable and mergeable with existing tooling.
• Engineering leads setting CI/CD policies can adopt DockSec's honest exit code convention (0 through 3) as a standard for ensuring pipeline failures surface accurately rather than silently passing gates they should not clear.