# Diagram evidence for audits

> Page: https://docs.plotwork.dev/diagram-evidence-for-audits. Index of every page: https://docs.plotwork.dev/llms.txt

How to keep the network, system and data-flow diagrams an auditor asks for current between audits, and what to hand over when the auditor asks. It is for the team that owns a SOC 2, ISO/IEC 27001, PCI DSS or HIPAA audit and the platform team that runs its CI.

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

| Question | Answer |
|---|---|
| What does Plotwork add to an audit? | Diagrams drawn from the code that builds the system, kept in step with it by a check in CI, with a record of every change: the commits, the check runs and, on Pro and Enterprise, the organisation's audit log. |
| How are the diagrams kept current? | `plotwork.config.json` names the files each diagram is made from. `plotwork generate --check` fails a pull request that changes them and leaves the diagram behind. |
| How is that enforced? | Make the check job a required status check in a branch ruleset on the default branch. |
| Who redraws a diagram? | The GitHub Action in write mode opens a pull request with the new diagram, and a person reviews and merges it. Hand edits live in an overrides file, so the next import keeps them. |
| What can I export? | The check's JSON report, SARIF and JUnit files, the git history of each diagram, and on Enterprise the audit log as CSV or JSON Lines. |
| Does the check send anything anywhere? | No. Check mode reads no secret and makes no network request. |
| How do I keep the tool itself fixed? | Pin the Action to a commit SHA and the command line to an exact version, and verify a release with its checksums. |

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

| Framework | Where diagrams are commonly requested | What to keep current |
|---|---|---|
| SOC 2 | The system description (description criteria DC 200: infrastructure, software, data and boundaries), and change management (CC8.1) | Network and data-flow diagrams of the system in scope, and a record that changes to it are reviewed |
| ISO/IEC 27001:2022 | Annex A 5.9 (inventory of information and other associated assets) and 8.20 (networks security) | Diagrams of the assets in scope and how the networks that hold them are separated |
| PCI DSS v4.0 | Requirement 1.2.3 (an accurate network diagram is maintained) and 1.2.4 (an accurate data-flow diagram is maintained) | The network diagram and the account data-flow diagram, as the environment changes |
| HIPAA Security Rule | The risk analysis, 45 CFR 164.308(a)(1)(ii)(A) | Where electronic protected health information is stored and how it moves |

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

```json
{
  "sources": [
    {
      "name": "infra",
      "from": "infra/**/*.tf",
      "format": "terraform",
      "out": "docs/infra.diagram"
    }
  ]
}
```

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](https://docs.plotwork.dev/importing-from-code-and-data.md) 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](https://docs.plotwork.dev/diagrams-as-code.md) has every option.

## 3. Make the check a required status check

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

```yaml
name: diagrams

on:
  pull_request:

permissions:
  contents: read

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.14
        with:
          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.

| Setting | Why |
|---|---|
| `contents: read` only | Check mode needs nothing else. It reads no secret and makes no network request, so it is safe on a pull request from a fork. |
| A required status check | Without it a failed check is a warning a person can merge past. |
| A nightly run without `since` | A new release of the Action can draw a picture differently, and no file change points at that. |

To redraw the diagrams for you, add the write mode workflow from [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md): 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.

| Evidence | Where it comes from | How to keep it |
|---|---|---|
| The check passing on a merge | The required status check on the pull request | Your repository host keeps it with the pull request |
| What the diagram looked like, and when it changed | The diagram and its pictures are files in the repository | `git log -- docs/infra.diagram` lists every version with its commit and time |
| A machine-readable record of the run | `report-file` (JSON), `sarif-file` (SARIF 2.1.0) and `junit-file` (JUnit XML) inputs of the Action, or `plotwork generate --check --format json` | Upload them as build artifacts, or send the SARIF file to code scanning |
| Who changed what in the organisation | The organisation's audit log, on Pro and Enterprise | On Enterprise, export it as CSV or JSON Lines, have your SIEM poll it with a key that can only read it, or [send each event as it happens](https://docs.plotwork.dev/siem-delivery.md) to Datadog, Dynatrace, Splunk, Microsoft Sentinel or a webhook |

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](https://docs.plotwork.dev/audit-log.md) 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:

| What | How |
|---|---|
| The GitHub Action | Pin it to its full commit SHA with the release in a comment, and let Dependabot move it in a pull request you review. |
| The command line | Run an exact version, such as `npx --yes @buun_group/plotwork@0.1.0-beta.13 generate --check`. |
| A release | Each Action release has `dist/checksums.txt`, the SHA-256 of the bundle and its notices; `sha256sum --check dist/checksums.txt` verifies it. The npm packages are published with provenance. |

[Enterprise rollout](https://docs.plotwork.dev/enterprise-rollout.md) has the Dependabot file and the reusable workflow for many repositories.

## 6. What to show an auditor

| Ask | Show |
|---|---|
| A current network or data-flow diagram | The diagram's picture from the default branch, and the commit it was last changed in |
| Evidence the diagram is accurate | The settings that name the files it is drawn from, and the required check that fails when it falls behind |
| Evidence changes are reviewed | The pull requests that changed the infrastructure, each with the check passing, and the regenerate pull requests a person merged |
| A history of the diagram | `git log` of the diagram, or its versions in the portal when it is published to the organisation |
| Who had access and what they did | The organisation's members and roles, and the audit log export |
| How the tool is controlled | The pinned Action and command line versions, the checksums, and that check mode makes no network request |

## See also

| Page | Why |
|---|---|
| [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md) | Sources, overrides, check and write mode |
| [Keep diagrams in sync in CI](https://docs.plotwork.dev/diagrams-in-ci.md) | The Action's commands and inputs |
| [Enterprise rollout](https://docs.plotwork.dev/enterprise-rollout.md) | Required checks, reports and pinning across many repositories |
| [Audit log](https://docs.plotwork.dev/audit-log.md) | What the organisation's log records, and its export |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | What the hosted service stores, and what it never does |