Skip to content
RingZero Docs

How security scanning works

RingZero runs offensive security tooling — AI agents that actively probe your hosts. Tooling like that must never double as an attack platform, so RingZero has no free-text target field: you cannot enter arbitrary IPs, CIDR ranges, or domains anywhere in the product.

Instead, a host becomes scannable only after your organization proves it controls it — by running the RingZero sidecar on that host. Deploy access is the proof of control: if you can run our sidecar next to your app, the host is yours to test. (What the scans themselves do is covered in the AI penetration testing product overview.)

The sidecar

Section titled “The sidecar”

The sidecar is a small static binary (also shipped as a container image, ghcr.io/ringzero/sidecar) that runs alongside your application — as a companion container in Docker Compose or Kubernetes, or as a daemon on the host. It has one job: register the host with your org and keep that registration fresh. It doesn’t proxy your application traffic, doesn’t touch your application, and idles at under 10 MiB of memory and under half a percent of one core (the binary is ~12 MB, the container image ~15 MB). (Scan probe traffic for private hosts is carried by a separate Scan Gateway, not the sidecar.)

┌─ your host ──────────────────────────┐
│  ┌───────────┐   ┌────────────────┐  │      ┌──────────────────┐
│  │  your app │   │ ringzero-      │  │      │  RingZero        │
│  │           │   │ sidecar        │──┼──────▶  control plane   │
│  └───────────┘   │  :7301 :7302   │◀─┼──────│  (attest,        │
│                  └────────────────┘  │      │   challenge,     │
└──────────────────────────────────────┘      │   heartbeat)     │
                                              └──────────────────┘

Two connectivity modes

Section titled “Two connectivity modes”

The diagram above is direct mode: RingZero connects back to the host to verify the challenge and to run scans. That’s the simplest path when the host is publicly reachable — but most infrastructure isn’t, and you should never expose an internal host to the internet just to scan it.

For private hosts, gateway mode puts a Scan Gateway inside your network. Sidecars talk only to the gateway; the gateway holds a single outbound tunnel to RingZero and runs scans from inside — nothing internal is exposed.

┌─ your private network ─────────────────────────────┐
│  ┌─────────────┐        ┌──────────────────┐       │      ┌──────────────┐
│  │ host + side-│ ──────▶│  ringzero-       │ ──────┼─────▶│  RingZero    │
│  │ car (mode:  │  7300  │  gateway         │  443  │  out │  control     │
│  │ gateway)    │◀────── │  (tunnel + scan  │◀──────┼──────│  plane       │
│  └─────────────┘        │   egress)        │       │      └──────────────┘
│   no inbound, no        └──────────────────┘       │
│   internet egress        outbound-only, no inbound │
└────────────────────────────────────────────────────┘

The rest of this page describes registration in direct-mode terms; gateway mode follows the same flow, just carried over the gateway. See Connectivity & network topologies for when to use each and how the trust model differs.

Registration flow

Section titled “Registration flow”

  1. Issue a registration token. An org admin generates a scoped, revocable registration token (rz_reg_…) in Settings → Hosts → Registration tokens. Tokens are per-org, expire, and can be rotated. See Sidecar authentication.

  2. Deploy the sidecar alongside your application, configured with the token — manually or with a downloaded config bundle.

  3. Attest. On startup the sidecar sends a signed attestation to RingZero: the org token plus host identity (hostname, addresses, platform metadata).

  4. Challenge–response. RingZero answers with a challenge that must be served back from the claimed host — in direct mode the control plane connects to the sidecar’s challenge listener (port 7301) at the attested address. This binds the registration to the host itself, so a leaked token can’t be replayed from somewhere else. Every attested address (IPv4 and IPv6) is verified independently; only verified addresses enter scan scope, and unverified ones are dropped with an address_unverified warning — a host registers as long as at least one address verifies. (In gateway mode the challenge is answered over the sidecar’s outbound connection to the gateway instead — no inbound, and the address-binding above becomes defense-in-depth rather than the third-party guarantee; see the connectivity trust model.)

  5. Registered. The host appears in Settings → Hosts with status active and becomes importable as a scan target.

  6. Stay fresh or fall out. The sidecar heartbeats every 60 seconds. A host that misses 3 heartbeats moves to expired and leaves scan scope automatically. Admins can revoke a host or a token at any time, effective immediately.

Host lifecycle

Section titled “Host lifecycle”
StatusMeaningIn scan scope?
activeRegistered, heartbeats currentYes
expiredHeartbeats stopped (sidecar down, host decommissioned, or deregistered)No — automatically
revokedExplicitly revoked by an adminNo — immediately

Decommissioned infrastructure drops out of scope on its own: stop the host (or just the sidecar) and the registration expires. Nothing you recycle to someone else stays scannable.

Scan-time enforcement

Section titled “Scan-time enforcement”

Registration gates import, but the scan engine re-checks at execution: every target of a run must resolve to a currently-active registered host belonging to the requesting org — at the moment the scan starts and while it runs. Expiry or revocation mid-run halts probing of that host. Host labels scope which registered hosts a scan targets. Every registration, revocation, and scan authorization is recorded in the org’s audit trail.

For gateway-mode hosts this check runs twice — RingZero authorizes the target (the authoritative gate, which also confines routing to approved private scopes), and an uncompromised Scan Gateway re-checks it before opening any probe connection inside your network.

Next steps

Section titled “Next steps”