Your cluster, our partners, one feed of findings
Run the samma operator in your Kubernetes cluster and connect it to samma.io. Every host you publish through an Ingress can then be scanned by partner vulnerability scanners and pentest services, through one connection. The results come back to your cluster as Prometheus metrics and log lines.
How it works
Three parties, one loop: your cluster tells samma.io what to scan, samma.io asks the partners you chose, and the findings flow back to where you already watch your systems.
Your cluster
- samma operator watches your Ingresses
- Collector exports results as metrics and logs
samma.io cloud
- Holds your targets and profiles
- Triggers partner scans, stores and formats results
Partner scanners
- Vulnerability scanners and pentest services
- Run from outside, against your endpoint
- 1
Install the operator
Install the samma operator in your own Kubernetes cluster with Helm. It runs Samma's open-source scanners inside the cluster.
- 2
Connect it to samma.io
Give the operator a samma.io API token. It now registers the hosts it scans as targets in your samma.io organisation, and the cluster shows up under Clusters.
- 3
Annotate an Ingress
Deploy an Ingress with samma-io.alpha.kubernetes.io/enable: "true". The operator picks up every host on it and registers it with samma.io.
- 4
samma.io triggers the partners
In samma.io you connect the partner scanners you want and enable them on a profile. Each new target in that profile is sent to those partners, and you can rescan at any time.
- 5
Results come back to you
samma.io collects each partner's result, turns it into findings and serves them with your other results. The collector in your cluster exports them as Prometheus metrics and log lines.
For clients
One operator in your cluster gives you Samma's own scanners plus every partner you connect in samma.io. You don't need an account with each vendor.
1. Install and connect
Create two tokens under Dashboard → API Tokens: one for the operator, and a read-only one for the collector that brings results back.
helm upgrade --install samma-operator \
oci://ghcr.io/samma-io/charts/samma-operator \
--namespace samma-io --create-namespace \
--set config.apiUrl=https://www.samma.io \
--set config.apiToken=<samma.io API token> \
--set clusterName=prod-eu \
--set collector.enabled=true \
--set collector.apiToken=<read-only samma.io token>2. Annotate your Ingress
Every host on an opted-in Ingress becomes a samma.io target. Partner scanners enabled on the target's profile scan it as soon as it arrives.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: checkout
annotations:
samma-io.alpha.kubernetes.io/enable: "true"
samma-io.alpha.kubernetes.io/profile: "web"
spec:
rules:
- host: checkout.example.comPrometheus metrics
The collector polls samma.io every 5 minutes and serves :9100/metrics. Partner results use the scanner name external:<partner>.
| Metric | Labels | Meaning |
|---|---|---|
| samma_findings | target, scanner, severity | Findings of the latest run, per severity |
| samma_scan_outcome | target, scanner, outcome | 1 for the latest run's outcome |
| samma_scan_last_finished_timestamp_seconds | target, scanner | When that run finished |
| samma_target_info | target, target_id, scanner_status, reachability | 1 per matched samma.io target |
Log lines
One JSON line per finding of each new run, on the collector's stdout, ready for Loki or any log shipper.
{"event":"samma.finding","target":"checkout.example.com",
"scanner":"external:samma-demo","runId":"cmwp…","severity":"INFO",
"title":"HTTPS reachable","host":"checkout.example.com","time":"…"}For partners
Offer your scanner or pentest service to every samma.io client through one small HTTP API. samma.io sends you targets and fetches your results; you never deal with the client's cluster.
One key per client
You issue an API key to the client. They paste it into samma.io when they connect your scanner, and every call samma.io makes for them carries it as a Bearer token. That is how you know who to bill.
Two endpoints
POST /scans starts a scan and returns its uuid. GET /scans/<uuid> returns the result once it is ready. samma.io asks for it when the client opens the target, and keeps asking until it is done.
JSON results
The result must be application/json. A findings list is turned into findings with severities; any other JSON is shown to the client as it is.
samma.io → partner: start a scan
POST {partner}/scans
Authorization: Bearer <client's key for this partner>
Content-Type: application/json
{ "target": "checkout.example.com", "port": 443,
"samma_id": "<samma.io target id>" }
→ 202 Accepted
{ "uuid": "05afc60c-464b-4b0a-97b1-4a0ce1b86fdb",
"status": "running", "started_at": "2026-11-20T16:45:09Z" }samma.io → partner: fetch the result
GET {partner}/scans/05afc60c-464b-4b0a-97b1-4a0ce1b86fdb
Authorization: Bearer <client's key for this partner>
→ 202 Accepted { "status": "running" }
→ 404 Not Found unknown scan
→ 200 OK Content-Type: application/json
{
"status": "completed",
"findings": [
{ "id": "TLS-OLD-PROTOCOL", "title": "TLS 1.0 enabled",
"severity": "high", "detail": "checkout.example.com:443 accepts TLS 1.0" }
]
}The rules of the API
- Accept only an IP address or a plain hostname as target, and validate it again on your side.
- Answer POST /scans within 10 seconds; run the scan in the background.
- Finish a scan within 24 hours. Until then, answer 202 for its uuid.
- Return the result as application/json, at most 1 MB. Other content types are rejected.
- Use status "failed" when a scan could not run. Failed runs are not billed.
- Severity is one of critical, high, medium, low or info. Anything else counts as info.
- Never log the client's key. It identifies the client, and samma.io stores it encrypted.
A minimal reference implementation is samma-io/external-scanner: a small Python service that does exactly this, with a placeholder scan you replace with your own.
The calls into samma.io
Your cluster talks to samma.io with two tokens: one to register targets, one read-only token to read results back.
Operator → samma.io: register a host
Sent for every host on an opted-in Ingress. samma.io keeps one target per profile and host, so repeated Ingress events don't create duplicates.
PUT /api/v1/targets
Authorization: Bearer <client's samma.io token>
X-Samma-Cluster: prod-eu
{ "value": "checkout.example.com", "type": "dns",
"label": "checkout.example.com", "profileId": "<optional>" }Collector → samma.io: read results
The latest run of every scanner on the target, Samma's own and the partners', in one shape.
GET /api/v1/targets/<id>/results
Authorization: Bearer <read-only samma.io token>
→ 200 OK
{
"targetId": "cmwp7rpj6…",
"runs": [
{ "scanner": "external:samma-demo", "runId": "cmwp8…",
"outcome": "succeeded", "finishedAt": "2026-11-20T16:50:02Z",
"findingCount": 1,
"severity": { "CRITICAL": 0, "HIGH": 1, "MEDIUM": 0, "LOW": 0, "INFO": 0 } }
],
"results": [
{ "scanner": "external:samma-demo", "runId": "cmwp8…",
"checkId": "TLS-OLD-PROTOCOL", "severity": "HIGH",
"title": "TLS 1.0 enabled", "host": "checkout.example.com",
"time": "2026-11-20T16:50:02Z" }
]
}Built for a security product
Findings are a map of how to break in. The integration is designed so they, and the keys behind them, stay with the people who own them.
Only your own targets
A scan is only sent for a target that belongs to your organisation, checked on the server before any partner is called.
Keys encrypted at rest
The key you get from a partner is stored with AES-256-GCM, sent only to that partner, never shown again and never logged.
Private hosts stay private
Hosts that resolve to private addresses, or not at all, are listed but never sent to a partner.
Evidence stays out of logs
The collector logs severity, title, host and time. Evidence and partner detail are never written to your logs.
Coming next
- Choose partner scanners per Ingress with an annotation, next to the profile they land in.
- Partner scans on a schedule, not only for new targets and rescans.
- Partners push results to samma.io when a scan is done, instead of samma.io asking.
Want your scanner or pentest service on samma.io, or want to connect your cluster?