Partner Revocation Program Integration Guide

Partner Revocation Program

Truffle Security continuously scans the public internet for secrets. As a service provider you can join the partner revocation program for free and receive these secrets.

Currently we scan these areas of the internet:

GitHub
GitLab
GitLab CI
Docker
NPM
PyPI
Firefox Add-ons
APK Pure
Android APK
Hugging Face

All secrets that we find are verified using TruffleHog before being sent to you. If you are a service provider and we do not currently support your secret type in our detectors, please raise a PR in the TruffleHog open-source repository and we can start scanning for your secrets.

How to join the program

Request access via this form. Please read the rest of this guide so you know what’s expected from your side.
After you request access, we will review your request.
Once approved, we will reach out and confirm your details. We may ask for more information if you’d like Truffle to also revoke secrets for you.
Implement a service to receive secrets from us.
Implement signature verification to ensure the messages you receive are from Truffle.
At any time, you can provide feedback by sending an email to partnerprogram@trufflesecurity.com.

What we send

We send a JSON array containing one verified secret per request to your webhook. All five fields are required strings; none should be omitted or empty.

Example request bodyJSON

[
  {
    "id": "example-finding-id",
    "token": "example-secret-not-a-real-key",
    "type": "ExampleDetector",
    "url": "https://github.com/trufflesecurity/trufflehog",
    "source": "Github"
  }
]

Payload fields
Field	Meaning
`id`	Unique finding identifier. Stays the same when we retry delivery.
`token`	The raw API key or secret.
`type`	The detector name.
`url`	The URL where we found the secret.
`source`	Discovery source, e.g. `Github`, `Docker` or `NPM`; it varies by finding.

Note: Each secret is verified before sending. We do not verify that the URL is still accessible. In some cases, the URL may not be accessible, but the secret is still active.

Any HTTP 2xx status counts as success. No response body or true/false-positive feedback is required.

Signature verification

The HTTP requests that we send to you contain headers that you can use to validate that the messages you receive are genuinely from Truffle Security. We highly recommend using them.

The two headers are:

Key identifier: Truffle-Public-Key-Identifier
Signature: Truffle-Public-Key-Signature

You can download the Truffle Security Partner Revocation Program public key and use it to validate messages using ECDSA P-256 with SHA-256.

Download public key (.pem)

Cache the key during setup; you do not need to download it for each request.

The signature covers the exact raw request body bytes. Verify it before parsing or reformatting the JSON.

Example HTTP POST we will send:

Example signed requestHTTP

POST /webhook HTTP/1.1
Host: partner.example.com
Content-Type: application/json
Truffle-Public-Key-Identifier: 182a7a4194659dcc955a2ab54709183843504dcfd2ba9b7a68e8207b2b1df9a5
Truffle-Public-Key-Signature: <base64-encoded DER signature>

[
  {
    "id": "example-finding-id",
    "token": "example-secret-not-a-real-key",
    "type": "ExampleDetector",
    "url": "https://github.com/trufflesecurity/trufflehog",
    "source": "Github"
  }
]

The endpoint and secret are illustrative. The signature is a placeholder; real requests contain a Base64-encoded ASN.1 DER ECDSA signature.

How to verify a signature

Save the public key in your service’s configuration.
Check that Truffle-Public-Key-Identifier matches the key identifier below.
Base64-decode the Truffle-Public-Key-Signature header. It contains an ASN.1 DER ECDSA signature.
Verify the signature over the original request body bytes using ECDSA P-256 with SHA-256 and the saved public key. Do this before parsing or reformatting the JSON.
Reject requests with missing headers, an unknown key identifier or an invalid signature.

Key identifier (SHA-256 of the public key’s DER SubjectPublicKeyInfo):
182a7a4194659dcc955a2ab54709183843504dcfd2ba9b7a68e8207b2b1df9a5

Credential Revocation

Adding a revocation endpoint is optional. However, under Section 3 of the Secret Scanning Partner Program Agreement, within 14 days of delivery you must either revoke each disclosed credential or notify Truffle in writing that revocation is not technically possible.

Truffle Security can automatically revoke tokens on your behalf. To set this up, provide a revocation URL in the request form and share the relevant API documentation with our team. We will confirm the integration details with you before enabling revocation.

We can send the same payload used for webhook notifications to your revocation URL, or work with your API’s request format using the documentation you provide. We’ll confirm the format and authentication requirements with you during setup.

Historical findings

Truffle Security will provide, when asked, a complete list of secrets we have discovered for your service. If you would like this, please let us know and we can provide them.

Partner Revocation ProgramIntegration Guide