Compliance evidence

Plotwork provides evidence for controls. It does not decide whether a control is met: your auditor does. Nothing on the page, in the export or on the badge says a repository or a company meets a framework.

TL;DR

1. Turn it on

1. Report drift from CI in each repository, with report-drift: true on the Action's generate step and a trusted publisher or an organisation key. The GitHub App's Enable sets this up in one pull request.
2. Open the organisation in the portal and choose Compliance evidence under Governance.
3. As an owner or admin, choose Settings on the page: the frameworks to show, and the window, in days, after which a diagram with no check is stale (14 by default, from 1 to 90).

Each run on a default branch from then on is kept as evidence. Runs sent before the plan included it are not.

2. The statuses

A check that could not make the diagram (an import error, for example) is inconclusive: the diagram keeps its last status and shows "Last check failed". A repository's status is the worst of its diagrams': Drifted, then Stale, then Current; Unknown when none has a check. Unverified diagrams are counted beside it and never change it.

PictureSourceOutline

3. Controls

Each diagram is suggested for the controls its format speaks to, and an owner or admin can add or take off any of them in the diagram's drawer. A change is recorded in the audit log.

Diagrams of data, folders or git history are suggested for none; map them by hand if your auditor accepts them. At the top of the page one figure says how many diagrams are current, with the five statuses beside it as filters. Under it each framework has a card with its share current, a row per control such as "1.2.4 Data-flow diagrams, 12 of 14", and its last 90 days; choose a card to show only the diagrams mapped to its controls. Unverified diagrams count in the total and never as current. Each control's text, how a diagram serves as evidence for it and where that evidence stops are in the page's tooltip and in the export. The ISO text is paraphrased, since the standard is copyrighted.

4. The evidence export

As an owner or admin, choose Export evidence, pick a framework (or all) and a date range of at most 400 days, and a format. The dialog shows what the pack will hold before you download it.

The pack holds the controls with their text; each diagram mapped to them with its repository, file and format; every check in the range with its date, commits, result and run link; each drift episode with its start, its resolution and the pull request that resolved it; the organisation's approval decisions in the range, when publish approval is used; the unverified diagrams with their hints; and a methodology that says what "current" means. Consecutive checks of one diagram with the same result on the same UTC day are one row with their count, the first and the last commit.

4.1 The report

The report is laid out as an audit document: a cover with your organisation, the framework's mark, the period, the time it was made and its document ID; a contents page; an executive summary with key figures, the share of diagrams current day by day and a bar per control; a section per control with its text, what Plotwork shows, where that evidence stops and every diagram mapped to it with links to the file, the run and the commit; the drift episodes and what fixed them; the methodology; an integrity section; and the check log as an appendix. Every page carries your organisation, the period, the document ID and "Page X of Y". Statuses are an icon and a word, so it prints in black and white.

To show the report has not been changed, the integrity section prints the SHA-256 of its evidence JSON, which the report offers as a download. Run shasum -a 256 on the file (or Get-FileHash -Algorithm SHA256 in PowerShell) and compare. The document ID is the first twelve characters of the same hash, so a report made again later is a new document.

4.2 Share with an auditor

As an owner or admin, choose Share with auditor, pick a framework and a period, and how long the link lasts: 7, 30 or 90 days. Choose who can open it:

The link is shown once: copy it then. The auditor sees the same document as the PDF, read-only, with the PDF, JSON and CSV downloads and no part of the portal. The list in the same box shows each link, how often it was opened, and Revoke. Every view is recorded in the audit log as orgs.evidence.share_view, with the auditor's address for a named link; making and revoking one are orgs.evidence.share. Only a hash of the link is kept. If your organisation shares only diagrams labelled Public, it makes no links: export the report and send it instead.

Each download is recorded in the audit log as orgs.evidence.export. The pack holds what is kept: checks follow the organisation's drift history (365 days by default on a contract), and while the organisation is on legal hold nothing is removed. At most 20,000 check rows fit in one pack; past that it says so, and a shorter range gets the rest.

5. The README badge

In a repository's menu, choose Badge, then Turn on. The dialog shows the Markdown once:

[![Plotwork diagrams](https://api.plotwork.dev/badges/evidence/<token>.svg)](https://docs.plotwork.dev/compliance-evidence)

6. Hand-drawn Mermaid

With the GitHub App linked, an owner or admin chooses Scan for Mermaid in a repository's menu. Plotwork reads the default branch's Markdown and Mermaid files (at most 16) and the files of the sources it detects (at most 12), converts each Mermaid diagram, and compares the names it draws with the names the code declares:

These are hints, not verification: a person names things their own way. Each diagram found is Unverified until it is drawn from a source.

Make it verifiable opens a pull request through the App on a branch named plotwork/verify-<source> that adds the matching source to the repository's plotwork.config.json, with the diagram and picture plotwork generate writes. Your Markdown is not changed: the pull request names the Mermaid block it is meant to replace, so you can put the generated picture in its place. Once the source's first check arrives, the finding shows as superseded. A repository with no plotwork.config.json needs Enable first, which draws every detected source in its setup pull request.

7. Privacy

The privacy policy has the full list and how long each is kept.

8. For auditors

See also