Phylax Attestations

An attestation is a signed statement that a specific artifact was analysed and reached a specific verdict. It is the durable record behind a verdict: a verdict tells you what to do now, an attestation lets you prove later what was known at the time, and it can be checked without asking Phylax anything.

What one contains

Field	Meaning
id	Identifier for this attestation
artifact	The exact artifact it covers, as a package URL
verdict	ALLOW, WARN or BLOCK at the time of signing
issued_at	When the statement was made
signature	Signature over the statement

The artifact is pinned to a version. An attestation for pkg:npm/express@4.18.2 says nothing about 4.18.3, which is the point: a new release is a new artifact and gets its own analysis.

Read the attestations for an artifact

JavaScript

const result = await phylax.attestations.list('pkg:npm/express@4.18.2')

curl

curl -s "https://api.phyi.dev/v1/attestations?artifact=pkg:npm/express@4.18.2" \
  -H "Authorization: Bearer $PHYLAX_API_TOKEN"

An artifact can carry more than one attestation. Analysis improves over time, so a package verified last month and again today has a record of both, and the newest one is the one a verdict reflects.

Verify one

1. Fetch the attestation

   Either from the API, or from wherever you archived it. Verification does not require the copy to come from us.

2. Check the signature

   const check = await phylax.attestations.verify(attestationId)
   if (!check.data.valid) {
     throw new Error(check.data.reason)
   }

3. Check it covers what you think it covers

   Compare the artifact field against the exact package and version you are about to install. A valid signature on the wrong artifact proves nothing about yours.

A signature is not a verdict

Verification tells you the statement is authentic and unmodified. It does not tell you the verdict was ALLOW. Read the verdict field as well, or a tampered-with build could pass a check that only tested the signature.

Where attestations show up

• The GitHub App and the Action use them to explain a check result.
• phylax attestations <artifact> prints them at the terminal.
• The SDKs expose them through attestations.list, attestations.get and attestations.verify.

Related

• How scoring works for what produces the verdict inside one
• The platform for where attestations sit end to end
• REST API for the full endpoint reference