Skip to main content

Infrastructure

Scan Attestations

Every scan produced by Sigil Bot is cryptographically signed and recorded in a public transparency log. This page explains how attestations work, how to verify them, and how to consume them programmatically.

How it works

When Sigil Bot completes a scan, it produces a signed attestation before publishing the result. The attestation chain follows three established standards:

1

in-toto Statement

The scan result is encoded as an in-toto Statement v1 with predicate type https://sigilsec.ai/attestation/scan/v1. The subject is the package being scanned, identified by its SHA-256 content hash.

2

DSSE Envelope

The statement is wrapped in a DSSE (Dead Simple Signing Envelope) with payload type application/vnd.in-toto+json and signed with Ed25519.

3

Transparency Log

The signed envelope is recorded in the Sigstore Rekor transparency log, producing an immutable log entry that anyone can audit.

Attestation predicate

The in-toto predicate contains the complete scan result. Nothing is omitted — the attestation is a tamper-evident record of exactly what Sigil found.

Predicate structure
{
  "scanner": {
    "uri": "https://sigilsec.ai",
    "version": "1.0.5",
    "phases": ["install_hooks", "code_patterns", "network_exfil", ...]
  },
  "scan": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "ecosystem": "npm",
    "package_name": "express",
    "package_version": "4.18.2",
    "verdict": "LOW_RISK",
    "risk_score": 0,
    "findings_count": 0,
    "files_scanned": 187,
    "duration_ms": 2340
  },
  "findings": [],
  "metadata": {
    "source": "npm-watcher",
    "bot_scan": true,
    "scanned_at": "2026-03-01T12:00:00Z",
    "content_hash_algorithm": "sha256",
    "content_hash": "a1b2c3d4..."
  }
}

Signing key

Sigil Bot signs attestations with an Ed25519 key. The public key and verification metadata are published as a well-known file:

bash
curl https://sigilsec.ai/.well-known/sigil-verify.json
AlgorithmEd25519
Encodingbase64-der
Key IDsha256:sigil-bot-signing-key-2026
Endpoint/.well-known/sigil-verify.json
Key rotation
When a signing key is rotated, the previous key is marked as revoked in the verify file and a new key is added. Old attestations remain verifiable against the key that signed them.

Verification steps

To verify a scan attestation manually:

1

Fetch the attestation from GET /api/v1/attestation/{scan_id}

2

Decode the DSSE envelope payload from base64url to JSON

3

Verify the in-toto Statement _type is https://in-toto.io/Statement/v1

4

Verify the predicateType is https://sigilsec.ai/attestation/scan/v1

5

Verify the subject digest matches the package archive SHA-256 from the registry

6

Verify the DSSE signature against the public key using Ed25519

7

Optionally verify the transparency log entry at Rekor using the log_entry_id

API endpoints

Fetch attestation

bash
curl https://sigilsec.ai/api/v1/attestation/{scan_id}

Returns the DSSE envelope, content digest, and transparency log entry ID. Responses are cached for 1 hour (attestations are immutable).

Verify attestation

bash
curl https://sigilsec.ai/api/v1/verify?scan_id={scan_id}

Server-side verification. Returns whether the attestation signature is valid, the signing key ID, and the timestamp.

Verify response
{
  "verified": true,
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "signed_at": "2026-03-01T12:00:00Z",
  "key_id": "sha256:sigil-bot-signing-key-2026",
  "log_entry": "24296fb24b8ad77a"
}

Verification SDKs

Use these libraries to verify attestations in your own tooling:

Node.js

bash
npm install @nomarj/sigil-verify
typescript
import { verify } from '@nomarj/sigil-verify';

const result = await verify({ scanId: '550e8400-...' });
console.log(result.verified); // true

Python

bash
pip install sigil-verify
python
from sigil_verify import verify

result = verify(scan_id="550e8400-...")
print(result.verified)  # True

CLI

bash
sigil verify --attestation https://sigilsec.ai/api/v1/attestation/{scan_id}

On scan reports

When a scan has a signed attestation, the report page shows a green SIGNED badge next to the scan date. If the attestation has a transparency log entry, a “(log)” link takes you to the Sigstore Rekor search page.

The attestation is also included in the page's JSON-LD structured data as a DigitalDocument schema, making it discoverable by AI agents and search engines.

See also

Previous← Sigil BotNextAgent Discovery →

Need help?

Ask a question in GitHub Discussions or check the troubleshooting guide.

CommunityTroubleshooting