Skip to content

Webhook scanners

A webhook scanner hands each scan job to your service and waits for a callback with the results. Use it for in-house or commercial scanners (Snyk, JFrog Xray, Dependency-Track, …) or to wrap a CLI Entrepot doesn’t run itself.

Terminal window
curl -fsS -H "Authorization: Bearer $ADMIN" -X POST $E/api/v1/scanners -d '{
"name": "xray", "type": "webhook",
"webhook": {"url": "https://scanner.example.com/entrepot", "secret": "<random HMAC key>", "timeoutSeconds": 900}
}'
curl -fsS -H "Authorization: Bearer $ADMIN" -X POST $E/api/v1/scanners/xray/test

server.baseURL must be set for webhook scanners, because the artifact and callback URLs are built from it.

For every job Entrepot sends:

POST https://scanner.example.com/entrepot
Content-Type: application/json
User-Agent: Entrepot-Scanner
X-Entrepot-Event: scan
X-Entrepot-Signature: sha256=<hex HMAC-SHA256(secret, body)>
{
"type": "scan",
"jobId": "…",
"scanner": "xray",
"repository": "npm-proxy",
"target": "package",
"component": {"id": "…", "name": "lodash", "version": "4.17.20", "format": "npm",
"purl": "pkg:npm/lodash@4.17.20"},
"artifactUrl": "https://entrepot.example.com/api/v1/scan-jobs/<id>/artifact?token=esj_…",
"callbackUrl": "https://entrepot.example.com/api/v1/scan-jobs/<id>/result",
"token": "esj_…",
"expiresAt": "…"
}
  • target is package (the artifact is the package file, identified by purl) or image (the artifact is an OCI image layout tar; component then also has image and digest).
  • The scanner test sends a signed {"type": "ping", "scanner": "…"} with X-Entrepot-Event: ping.

Always verify the signature before doing any work: compute HMAC-SHA256(secret, raw body), hex-encode it, and compare it with the header (after sha256=) in constant time.

  1. Acknowledge the POST with any 2xx. Do the scan asynchronously.

  2. Fetch the artifact (optional) from artifactUrl. The token is already in the query string; you can also send it as Authorization: Bearer <token>. Docker images come as an OCI layout tar.

  3. Post the result to callbackUrl with the token as Authorization: Bearer <token> (or ?token=). The body is one of:

    {"format": "entrepot", "findings": [
    {"vulnId": "CVE-2021-23337", "severity": "high", "package": "lodash",
    "installedVersion": "4.17.20", "fixedVersion": "4.17.21",
    "title": "Command injection in template()", "url": "https://nvd.nist.gov/vuln/detail/CVE-2021-23337"}
    ]}
    • {"format": "sarif", "document": { …SARIF 2.1… }}
    • {"format": "cyclonedx", "document": { …with vulnerabilities[]… }}
    • {"error": "…"} — the scan failed; the job is retried.
    • {"unsupported": true} — the scanner can’t scan this kind of artifact.

    Severities are critical, high, medium, low or unknown. A successful callback returns 204.

The token is single-use and expires after timeoutSeconds (default 900s); the job is then retried with backoff, up to three attempts by default.

receiver.py
import hashlib, hmac, json, os, threading, urllib.request
from http.server import BaseHTTPRequestHandler, HTTPServer
SECRET = os.environ["ENTREPOT_WEBHOOK_SECRET"].encode()
def scan_and_report(job):
findings = [] # run your scanner against job["component"]["purl"] or the artifact
body = json.dumps({"format": "entrepot", "findings": findings}).encode()
req = urllib.request.Request(job["callbackUrl"], data=body, method="POST", headers={
"Authorization": "Bearer " + job["token"], "Content-Type": "application/json"})
urllib.request.urlopen(req, timeout=30)
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
raw = self.rfile.read(int(self.headers["Content-Length"]))
want = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(want, self.headers.get("X-Entrepot-Signature", "")):
self.send_response(401); self.end_headers(); return
job = json.loads(raw)
self.send_response(202); self.end_headers()
if job["type"] == "scan":
threading.Thread(target=scan_and_report, args=(job,)).start()
HTTPServer(("", 8000), Handler).serve_forever()