Diagram evidence for audits

Plotwork is a tool for producing diagram evidence; your auditor decides what satisfies a control. Plotwork itself is not certified against these frameworks, and using it does not make a company compliant.

TL;DR

1. What auditors ask for

The frameworks below commonly call for diagrams as evidence. The clause is where an auditor most often asks; how the diagrams are judged is between you and your auditor.

2. Draw the diagrams from the code

Add a source for each diagram to plotwork.config.json at the root of the repository: the files it is made from, their format, and where the diagram is written.

1{2  "sources": [3    {4      "name": "infra",5      "from": "infra/**/*.tf",6      "format": "terraform",7      "out": "docs/infra.diagram"8    }9  ]10}

Run npx @buun_group/plotwork generate once and commit what it writes: the diagram, its pictures in light and dark, and nothing else. Terraform, Kubernetes manifests, Docker Compose, OpenAPI, SQL, Prisma and the other formats of Importing from code and data are read. Nothing is fetched and no code in the files is run.

A change you make by hand, such as a clearer label or a group, goes in the overrides file beside the diagram (docs/infra.overrides.json), never in the diagram itself, so the next import keeps it. Diagrams as code has every option.

3. Make the check a required status check

Run the check on every pull request, here in GitHub Actions:

1name: diagrams2
3on:4  pull_request:5
6permissions:7  contents: read8
9jobs:10  drift:11    runs-on: ubuntu-latest12    steps:13      - uses: actions/checkout@v714        with:15          persist-credentials: false16      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1417        with:18          command: generate

The samples pin the latest release of the Action by its commit. @v1 becomes available at the first stable release.

Then, in the repository's settings, add a branch ruleset on the default branch that requires the drift job to pass. A pull request that changes the infrastructure and leaves a diagram behind cannot merge until the diagram is redrawn.

To redraw the diagrams for you, add the write mode workflow from Diagrams as code: on a push to the default branch or on a schedule, the Action opens a pull request titled docs: regenerate diagrams from their sources from the branch plotwork/diagrams. A person reviews and merges it, which is the review an auditor looks for.

4. Keep the evidence

Each of these is made by the run itself; keep them where your audit evidence lives.

The audit log records members, roles, keys, published diagrams, locks, drift reports from CI and changes made by Plotwork support. It never records a diagram's source, a key's value, a token or a full IP address. Audit log has the event, how long each plan keeps it, and the export.

5. Pin the versions

An audit asks whether the tool that made the evidence could change under you. Fix it:

Enterprise rollout has the Dependabot file and the reusable workflow for many repositories.

6. What to show an auditor

See also