How codacy/codacy-trivy works
Project type and purpose (what you’re diagramming)
This repo is a Go-based “engine” Docker image used by Codacy to run Trivy scans against a mounted source directory. It is not a web service; it’s a batch CLI tool packaged as a container, intended to integrate with Codacy’s external-tools contract (tested via codacy-plugins-test).
Key signals:
• Dockerfile + README “docker engine we use at Codacy”
• cmd/tool (main scanner entrypoint) and internal/tool/* (orchestration, scanning, output)
• internal/trivy.go (integration/wrapper around the Trivy library)
• cmd/docgen + internal/docgen/* (documentation generator for Codacy rule/docs)
• .circleci/config.yml mentions keeping Trivy DB compatibility; versioning section indicates daily DB refresh behavior (CI-driven image rebuild/update)
• Inputs: repo/source mount (/src) + config/rules (Codacy patterns)
• Processing: tool runner → Trivy library/DB → post-processing (incl. malicious packages scanning)
• Outputs: machine-readable results consumed by Codacy (and docs artifacts generated by docgen)
How to read the file structure into architecture blocks
Use the tree to break the system into “deployable/runtime units” and “internal modules”:
Docker Image (codacy-trivy)
• Built by Dockerfile
• Run via docker run -v $srcDir:/src …
CLI executable: cmd/tool
• cmd/tool/main.go is the runtime entrypoint inside the container
CLI executable: cmd/docgen
• cmd/docgen/main.go generates documentation from rules/metadata
• internal/tool/*
• tool.go, runner.go: orchestration / lifecycle (parse args, decide what scanners run, formatting results)
• malicious_packages_scanner.go: additional scanning logic beyond vanilla Trivy (likely analyzing lockfiles)
• error.go: error types and mapping to tool exit/report semantics
• internal/trivy.go
• wrapper around Trivy library invocation + interpretation
• internal/docgen/*
• rule definitions (rule.go) + generation (docgen.go) + error handling
What the README implies about runtime interactions (data flow)
From the README usage:
• User/Codacy runs the image with a bind mount: -v $srcDir:/src
• Tool scans that directory using Trivy (which depends on vulnerability DBs and the Trivy library)
• Output is consumed by Codacy (and validated by codacy-plugins-test)
Also important:
• “latest version updated daily with new versions of Trivy’s vulnerability DBs”
→ Your architecture should include a DB refresh/rebuild pipeline (CI job pulls DBs / bakes them into image layer or caches them).
A CI/CD + supply cha
• GitHub (repo)
• CircleCI pipeline (.circleci/config.yml)
• Docker Build
• Trivy DB download step (compatibility tied to Trivy version)
• Docker Registry (where tag 1.2.3 gets refreshed daily)
• Dependabot / GitHub Workflows (dependency PRs / automation)
• GitHub commit/tag → CircleCI build
• CircleCI → fetch Trivy DBs (compatible version)
• CircleCI → build/push image tag (same version tag updated daily)
• Codacy Workers → pull image (must pull latest for same tag)
This explains the README “same tag updated daily” behavior, which is otherwise surprising and important for consumers.
Mandatory elements
• Clear labels that match repo terminology:
• “codacy-trivy image”, “cmd/tool”, “internal/trivy”, “internal/tool/runner”
• “mount”, “read”, “scan”, “aggregate findings”, “emit report”, “pull DB”, “push image”
• Rounded rectangles for executables/modules
• Boundaries:
• “Inside container” vs “Outside container”
• “CI time” vs “Runtime”
Practical “don’t overthink it” decomposition (maximize components)
Split aggressively:
• Separate “Trivy library” from “Trivy DB”
• Separate “malicious packages scanner” from “vulnerability scanning”
• Separate “doc generation” from “scan runtime”