Axon Shaft docs

Private security advisories

How a blocking security finding goes into a private draft advisory, what a public pull request shows instead, and who can open the draft.

On a public repo, anyone can read a pull request's comments. With private draft advisories on, a blocking finding from the Security checklist goes into a private draft security advisory on the repo, and the pull request gets a short note with the draft's link in place of the details.

The setting

It's the advisories setting: Private draft advisories for blocking security findings, in the Review section of the account's or the project's settings.

ValueWhat happens
Public repos (default)Drafts are opened on public repos. A private repo keeps the full finding in its comments.
OffNo drafts. Every finding is posted as it is.

It needs the app's Repository security advisories (Read and write) permission. Until the installation approves it, findings are posted as they would be without the setting. The card links to approve it on GitHub.

What happens on a review

  1. Before posting anything, the action asks the Axon Shaft API for a draft for each blocking Security finding, the first 3 on each review.
  2. The API opens the draft with a token only it holds, for that repo and that permission alone. The action never holds Repository security advisories write.
  3. A later review of the same finding gets the draft it already has, so a push doesn't open a second one.

The draft's summary is the finding's title. Its description has the finding's text, the lines and the pull request it was found on, and a line saying Axon Shaft's review opened it and that maintainers should check it. Every draft starts at high severity.

What the pull request shows

On a public repo, the finding's title reads "Security issue, reported privately", and its text says the details are in a private draft security advisory that the repo's admins and security managers can open, with the link. The inline comment, the summary comment, the Axon Shaft / security check run and the run's page on the dashboard all show only this note, and the suggested change is dropped.

The finding stays blocking, so the Security checklist's check run still fails.

The setting's third value, all, also opens drafts on private and internal repos, where the finding keeps its text and links to its draft. The dashboard offers only Off and Public repos, and shows All repos in the badge for an account set to it.

Who can open the draft

The repo's admins, its security managers and the advisory's collaborators. Publishing the advisory, setting its severity, CWE and credits, and requesting a CVE are up to the maintainers on GitHub. Axon Shaft never publishes a draft.

When a draft can't be opened

If the API refuses, the permission isn't approved, or GitHub's call fails, the finding is posted as it would be without the setting. The job log warns with advisory_failed, and the summary has a Draft advisories line naming the finding's fingerprint and the reason.

A dry run logs Would open a draft advisory for <fingerprint> and opens none.

Last updated on