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.
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/testserver.baseURL must be set for webhook scanners, because the artifact and
callback URLs are built from it.
The request
Section titled “The request”For every job Entrepot sends:
POST https://scanner.example.com/entrepotContent-Type: application/jsonUser-Agent: Entrepot-ScannerX-Entrepot-Event: scanX-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": "…"}targetispackage(the artifact is the package file, identified bypurl) orimage(the artifact is an OCI image layout tar;componentthen also hasimageanddigest).- The scanner test sends a signed
{"type": "ping", "scanner": "…"}withX-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.
Responding
Section titled “Responding”-
Acknowledge the POST with any
2xx. Do the scan asynchronously. -
Fetch the artifact (optional) from
artifactUrl. The token is already in the query string; you can also send it asAuthorization: Bearer <token>. Docker images come as an OCI layout tar. -
Post the result to
callbackUrlwith the token asAuthorization: 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,loworunknown. A successful callback returns204.
The token is single-use and expires after timeoutSeconds (default 900s);
the job is then retried with backoff, up to three attempts by default.
A minimal receiver
Section titled “A minimal receiver”import hashlib, hmac, json, os, threading, urllib.requestfrom 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()