# codacy/codacy-trivy architecture

> Architecture diagram of the GitHub repository codacy/codacy-trivy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codacy/codacy-trivy
- Repository: https://github.com/codacy/codacy-trivy

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0/1: Context + Runtime
  %% =========================

  subgraph "System Context (Runtime)"
    direction TB

    CodacyWorker["Codacy Worker (External Orchestrator)"]:::external
    CodacyIngest["Codacy Results Ingestion (Consumer)"]:::external
    SourceRepo[/"Source Code Repo<br/>(mounted as /src)"/]:::data
    TrivyDB[("Trivy Vulnerability DB<br/>(cached/baked conceptually)")]:::db
    ResultsDoc["Scan Report<br/>(Codacy-compatible output)"]:::artifact

    subgraph "codacy-trivy Docker Container (Batch CLI)"
      direction TB

      ToolBin(["tool (cmd/tool)"]):::exec
      Runner(["internal/tool.Runner<br/>(sequencing & aggregation)"]):::module
      TrivyAdapter(["internal/trivy<br/>(Trivy lib wrapper)"]):::module
      MalPkg(["internal/tool.MaliciousPackagesScanner<br/>(lockfile-based checks)"]):::module
      ErrMap(["internal/tool/error<br/>(exit/report semantics)"]):::module
      Formatter(["Report Formatter<br/>(structured results)"]):::module

      ToolBin -->|"calls"| Runner
      Runner -->|"invokes"| TrivyAdapter
      Runner -->|"invokes"| MalPkg
      Runner -->|"maps_errors"| ErrMap
      Runner -->|"formats"| Formatter
      Formatter -->|"emit_report"| ResultsDoc
    end

    CodacyWorker -->|"docker_run"| ToolBin
    SourceRepo -->|"bind_mount_/src"| ToolBin
    TrivyAdapter -->|"read/use_db"| TrivyDB
    ResultsDoc -->|"ingest"| CodacyIngest
  end

  %% =========================
  %% Level 2: Doc generation path
  %% =========================
  subgraph "Documentation Generation (Offline/CI or Local)"
    direction TB

    DocgenBin(["docgen (cmd/docgen)"]):::exec
    DocgenCore(["internal/docgen/docgen<br/>(generator)"]):::module
    DocgenRules(["internal/docgen/rule<br/>(rule metadata)"]):::module
    DocgenErr(["internal/docgen/error<br/>(error handling)"]):::module
    DocsDesc[/"docs/description<br/>(rules/docs artifacts)"/]:::artifact
    OpenSSF["Aux Script: OpenSSF index build"]:::ops

    DocgenBin -->|"calls"| DocgenCore
    DocgenCore -->|"reads"| DocgenRules
    DocgenCore -->|"handles"| DocgenErr
    DocgenCore -->|"writes"| DocsDesc
    OpenSSF -->|"indexes"| DocsDesc
  end

  %% =========================
  %% CI/CD lane: daily DB refresh + rebuild
  %% =========================
  subgraph "CI/CD & Supply Chain (Daily Refresh Behavior)"
    direction TB

    GitHubRepo["GitHub Repository"]:::external
    CircleCI["CircleCI Pipeline"]:::cicd
    GHDependabot["Dependabot Config"]:::cicd
    GHWorkflows["GitHub Actions Workflows"]:::cicd
    DBDownload["Download/Refresh Trivy DB<br/>(compatibility aligned with Trivy version)"]:::cicd
    DockerBuild["Docker Build (codacy-trivy image)"]:::cicd
    Registry[("Docker Registry<br/>(tag updated daily)")]:::registry

    GitHubRepo -->|"commit/tag_triggers"| CircleCI
    GHDependabot -->|"dependency_prs"| GitHubRepo
    GHWorkflows -->|"automation"| GitHubRepo

    CircleCI -->|"pull_db"| DBDownload
    DBDownload -->|"bake/cache_db"| DockerBuild
    CircleCI -->|"build"| DockerBuild
    DockerBuild -->|"push_image"| Registry

    Registry -->|"pull_latest_tag"| CodacyWorker
  end

  %% =========================
  %% Testing/contract fixtures
  %% =========================
  subgraph "Testing & Contract Validation"
    direction TB
    PluginsTest["codacy-plugins-test<br/>(external-tools contract validator)"]:::external
    Fixtures[/"docs/multiple-tests<br/>(fixtures: lockfiles + expected results)"/]:::test

    PluginsTest -->|"runs_engine"| ToolBin
    Fixtures -->|"inputs/expected_outputs"| PluginsTest
  end

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click ToolBin "https://github.com/codacy/codacy-trivy/blob/master/cmd/tool/main.go"
  click DocgenBin "https://github.com/codacy/codacy-trivy/blob/master/cmd/docgen/main.go"
  click Runner "https://github.com/codacy/codacy-trivy/blob/master/internal/tool/runner.go"
  click ErrMap "https://github.com/codacy/codacy-trivy/blob/master/internal/tool/error.go"
  click MalPkg "https://github.com/codacy/codacy-trivy/blob/master/internal/tool/malicious_packages_scanner.go"
  click TrivyAdapter "https://github.com/codacy/codacy-trivy/blob/master/internal/trivy.go"
  click DocgenCore "https://github.com/codacy/codacy-trivy/blob/master/internal/docgen/docgen.go"
  click DocgenRules "https://github.com/codacy/codacy-trivy/blob/master/internal/docgen/rule.go"
  click DocgenErr "https://github.com/codacy/codacy-trivy/blob/master/internal/docgen/error.go"
  click CircleCI "https://github.com/codacy/codacy-trivy/blob/master/.circleci/config.yml"
  click GHDependabot "https://github.com/codacy/codacy-trivy/blob/master/.github/dependabot.yml"
  click GHWorkflows "https://github.com/codacy/codacy-trivy/tree/master/.github/workflows/"
  click Fixtures "https://github.com/codacy/codacy-trivy/tree/master/docs/multiple-tests/"
  click DocsDesc "https://github.com/codacy/codacy-trivy/tree/master/docs/description/"
  click OpenSSF "https://github.com/codacy/codacy-trivy/blob/master/scripts/build_openssf_index.py"
  click DockerBuild "https://github.com/codacy/codacy-trivy/tree/master/Dockerfile"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0b1b3a
  classDef exec fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#052e16
  classDef module fill:#bbf7d0,stroke:#166534,stroke-width:1px,color:#052e16
  classDef data fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#111827
  classDef db fill:#e0f2fe,stroke:#0369a1,stroke-width:1px,color:#0c4a6e
  classDef artifact fill:#fef9c3,stroke:#a16207,stroke-width:1px,color:#3b2f0b
  classDef cicd fill:#f3e8ff,stroke:#6d28d9,stroke-width:1px,color:#2e1065
  classDef registry fill:#cffafe,stroke:#0e7490,stroke-width:1px,color:#083344
  classDef test fill:#ffe4e6,stroke:#9f1239,stroke-width:1px,color:#4c0519
  classDef ops fill:#ffedd5,stroke:#c2410c,stroke-width:1px,color:#431407
```
