Podman

Connect a Podman host to Safeguard, or scan it on the host with the Safeguard CLI. The access each connection needs, which credentials work, and step-by-step setup.

Availability

This integration is switched on per workspace. If you do not see the card under Integrations, ask your Safeguard contact. The safeguard podman CLI commands work in every workspace.

What it does

The Podman card connects Safeguard to the images in a Podman store, read through the Podman REST API (the service podman system service runs). Safeguard lists every image repository and tag on the host and how many running containers use each one. Each image you select becomes a project that Safeguard scans for an SBOM and vulnerability findings. Every scan resolves the tag to its image ID on the host, streams exactly that image to the scanner and records its digest. Find the card under Integrations on the Project/Product tab.

Images Podman pulled from a registry (Docker Hub, Quay, GitHub Container Registry, Amazon ECR, Oracle Container Registry and others) are already covered by that registry's integration. Use Podman for what is on the host itself, including images built there.

There are two ways in:

On the host, with the Safeguard CLI (recommended for hosts the internet cannot reach). safeguard podman scan reads the local Podman socket. No Docker and no inbound connection are needed.
Hosted, with the Podman card. Safeguard's scanner connects to the host over SSH or mutual TLS. Only public addresses are reached.

Public vs private

	Public	Private
What you enter	Not available	The Podman service URL and an SSH key or a TLS client certificate
Credential needed	Not available	An SSH key with the host's public key, or a TLS client certificate and key
What you can scan	Not available	Every image in the Podman store the URL points at

Podman has no anonymous API, so every connection is private.

Supported auth methods

Method	Use it when	Notes
SSH to the Podman socket (`ssh://`)	The host accepts SSH from the internet (recommended)	The same channel `podman --remote` uses. The host key is always verified.
Mutual TLS to the service (`tcp://`)	You run the service on a TCP port with TLS	Needs Podman 5.7 or later (`--tls-cert`, `--tls-key`, `--tls-client-ca`).
Mutual TLS through a proxy (`https://`)	A reverse proxy in front of the socket terminates TLS	The proxy must require a client certificate.
Safeguard CLI on the host	The host is not reachable from the internet	Reads the local socket as the user that runs it.

Permissions required

Safeguard only reads from Podman: it lists images and containers and exports images. It never creates, starts, stops or deletes anything. Podman has no read-only API role: anyone who can open the Podman socket controls Podman as the user that owns it (podman-system-service(1)). The least-privilege setup is a dedicated rootless user that only holds the images you want scanned.

SSH to the Podman socket

Permission / scope	Required?	What Safeguard uses it for
SSH login as the socket's user (public key in `~/.ssh/authorized_keys`)	Required	Opening the SSH connection. Password logins are not used.
Read and write on the socket file (`/run/user/<uid>/podman/podman.sock`, mode `srw-rw----`, owned by that user)	Required	Connecting to the Podman API through SSH stream forwarding.
SSH stream forwarding (`AllowStreamLocalForwarding`, on by default in OpenSSH)	Required	Reaching the remote unix socket, as `podman --remote` does.
Root, or the rootful socket `/run/podman/podman.sock`	Optional	Only for images stored by rootful Podman.

Least privilege: a dedicated user with lingering on (loginctl enable-linger <user>), its rootless socket, and only the images to scan in its store.

Mutual TLS

Permission / scope	Required?	What Safeguard uses it for
A client certificate signed by the CA in the service's `--tls-client-ca`	Required	Authenticating to the Podman API.
The CA that signed the service certificate	Optional	Verifying the server when its certificate is not from a public CA.

Least privilege: run the TLS service as a dedicated rootless user, as above, and issue one client certificate for Safeguard.

Safeguard CLI on the host

Permission / scope	Required?	What Safeguard uses it for
Run as the user that owns the images (rootless) or root (rootful)	Required	Opening the local Podman socket.
A running API socket (`podman.socket`)	Required	The Podman REST API the CLI reads.
The `podman` binary	Optional	Only for `--via save`.

Least privilege: run the CLI as the rootless user whose images you scan.

Token types

Token type	Works?	Notes
SSH key (ed25519, ECDSA or RSA, OpenSSH or PEM format)	Yes (recommended)	An encrypted key needs its passphrase.
TLS client certificate and key (PEM)	Yes	Signed by the service's client CA.
Password or API token	No	The Podman API has none; SSH passwords are not accepted.
Plain `tcp://` or `http://` without TLS	No	Unencrypted and unauthenticated, so the hosted connection refuses it. The CLI allows it on a port you control, with a warning.

Expiry: rotate SSH keys and client certificates on your normal schedule, for example every 90 days. An expired certificate or a removed key makes validation and scans fail with an authentication error.

What we never need: a root password, registry credentials (the registry integrations cover registries), write access to images or containers, or any change on the host.

Step-by-step setup

Create the credential on the host

As the user that owns the images, start the API socket: systemctl --user enable --now podman.socket. Keep it running after logout with sudo loginctl enable-linger <user>. For rootful Podman use sudo systemctl enable --now podman.socket.
For SSH: create a key pair for Safeguard (ssh-keygen -t ed25519 -f safeguard-podman -C safeguard) and add safeguard-podman.pub to that user's ~/.ssh/authorized_keys. Print the host key with ssh-keyscan -t ed25519 <host> and check its fingerprint with the host's owner.
For mutual TLS (Podman 5.7 or later): issue a server certificate for the host name and a client certificate from your CA, then run podman system service --time 0 --tls-cert server.pem --tls-key server-key.pem --tls-client-ca ca.pem tcp://0.0.0.0:8888.

Or with the Safeguard CLI on the host

safeguard podman ping                       # finds the socket and shows the Podman version
safeguard podman images                     # every image with its ID and digest
safeguard podman containers --all           # containers with the digest of the image they run
safeguard podman inventory --json           # running containers grouped by image digest
safeguard podman scan --running             # scan the images of running containers
safeguard podman scan --all --json          # scan every image in the store
safeguard scan --image podman:docker.io/library/alpine:3.20
safeguard scan --image oci-archive:./alpine.tar   # from podman image save --format oci-archive

The CLI finds the socket like podman --remote: --url, then CONTAINER_HOST, then $XDG_RUNTIME_DIR/podman/podman.sock, then /run/user/<uid>/podman/podman.sock, then /run/podman/podman.sock. It can also reach another host: --url ssh://<user>@<host>/run/user/<uid>/podman/podman.sock --identity <key> (host keys are checked against ~/.ssh/known_hosts), or --url tcp://<host>:8888 --tls-ca ca.pem --tls-cert client.pem --tls-key client-key.pem. Results stay on the machine. See CLI usage.

Connect it in Safeguard

Open Integrations and choose the Project/Product tab.
Click Connect on the Podman card.
Enter a Name, then choose SSH or Mutual TLS under Connection.
Enter the Podman service URL: ssh://<user>@<host>[:port]/run/user/<uid>/podman/podman.sock (rootless), ssh://root@<host>/run/podman/podman.sock (rootful), tcp://<host>:<port> or https://<host>.
For SSH, paste the SSH private key, its Key passphrase if it has one, and the Host public key. For mutual TLS, paste the Client certificate (PEM), the Client private key (PEM) and, for a private CA, the CA certificate (PEM).
Click Verify connection. Success shows how many images are on the host.
Click Next, pick the image repositories and tags to scan, and finish.

Webhooks and triggers

Podman has no webhooks. Images are scanned when you connect them, on the schedule you set under Integrations > Scheduled, or when you rescan by hand.

What we read and store

Read: the Podman version, the image list, the container list, and for each scan the selected image, exported as an OCI archive (GET /_ping, /v4.0.0/libpod/version, /v4.0.0/libpod/images/json, /v4.0.0/libpod/containers/json, /v4.0.0/libpod/images/{id}/json, /v4.0.0/libpod/images/{id}/get). Nothing is written to the host.
Stored: the SBOM, the findings, and the image ID and digest of each scan. The service URL and credential are encrypted at rest and never shown again after you save them.
Not stored: the image archive is deleted with the scan's working folder when the scan ends.
No customer data from this integration is sent to third-party LLMs.

Troubleshooting

Message you see	Cause	Fix
`the SSH host key of <host> is not known`	The host key is missing or the pasted key is wrong.	Paste the output of `ssh-keyscan <host>` after checking its fingerprint.
`the SSH host key of <host> does not match the one on record`	The host offered a different key.	If the host was rebuilt, update the host key. Otherwise do not connect.
`SSH login to <host> as "<user>" was refused`	The public key is not in that user's `authorized_keys`, or the user name is wrong.	Add the key, and check the user in the URL.
`cannot open the Podman socket <path>`	The socket is not running, or the user cannot open it.	Run `systemctl --user enable --now podman.socket` as the socket's user, and connect as that user.
`the service refused the client certificate`	The client certificate is not signed by the service's `--tls-client-ca`.	Issue the client certificate from that CA.
`the server certificate is not signed by a trusted CA`	The service uses a private CA.	Paste that CA in CA certificate (PEM).
`did not answer with TLS`	The service runs without `--tls-cert` and `--tls-key`.	Start it with TLS (Podman 5.7 or later) or put a TLS proxy in front.
`answered, but not as Podman`	The URL points at a Docker daemon or a proxy that does not forward to Podman.	Point it at `podman system service`.
`resolves to ... a private, loopback or link-local address`	The hosted scanner never connects to private addresses.	Run `safeguard podman scan` on the host instead.

Rotation and disconnect

Rotate: create the new key or certificate, open the connection's edit dialog, paste the new credential, click Verify connection and save. Then remove the old public key from authorized_keys, or revoke the old certificate.
Disconnect: delete the connection under Integrations, then remove Safeguard's public key from authorized_keys or revoke its client certificate. Stop the TLS service if you started it only for Safeguard.

Limits

The Podman API returns the whole image list in one answer; Safeguard reads all of it.
Container code analysis does not run for images scanned from a Podman host.
The running-container inventory is CLI output (safeguard podman inventory); it is not shown in Detection & Response yet.
safeguard podman scan results stay on the machine; they are not uploaded to the platform.

Vendor references

podman-system-service(1), checked 2026-10-16.
podman-remote(1), checked 2026-10-16.
podman(1) global options (--url, --identity, --tls-ca, --tls-cert, --tls-key), checked 2026-10-16.
Podman REST API reference, checked 2026-10-16.
Podman v5.7.0 release announcement (TLS and mTLS for the API service), checked 2026-10-16.

Podman

On this page