Skip to main content

Podman

Podman integration allows your product to connect with container registries and local container environments managed by Podman to fetch image metadata, list containers, inspect running workloads, and analyze image configurations. This integration helps in vulnerability scanning, asset inventory, and container compliance for environments where Podman is used as a daemonless container engine (often an alternative to Docker).

Credentials Needed​

Podman itself is daemonless and uses the same authentication mechanism as Docker when connecting to remote or registry-based images. The required credentials depend on whether you are connecting to a remote container registry (like Docker Hub, Quay.io, or a private registry) or a local Podman environment.

For Remote Registries (e.g., Docker Hub, Quay, ECR, GCR):

  • Registry Username
  • Registry Password or Access Token

For Local Podman Integration:

  • No credentials are needed for local CLI-based or socket-based integrations (e.g., /run/user/<UID>/podman/podman.sock)
  • Ensure your product has access to the Podman socket or API endpoint

Permissions Needed / API Permissions​

Podman uses container registry permissions (based on the registry type) and local system-level permissions.

ContextRequired AccessDescription
Local Podman EnvironmentSocket or API access (podman.sock)To list, inspect, or manage local containers and images
Remote Container RegistriesRead-only access (repository:read)To list and fetch container images
Private RegistriesToken or Basic AuthFor authentication against secure registries

For integrations that only need to read metadata or analyze images, ensure read-only permissions are granted.

Creating Users / Access Tokens​

For Remote Registries​

Use the registry's native credential mechanism to authenticate Podman. For example:

# Docker Hub
podman login docker.io -u <USERNAME> -p <ACCESS_TOKEN>

# Quay.io
podman login quay.io -u <USERNAME> -p <ACCESS_TOKEN>

# Private registry
podman login <registry-url> -u <USERNAME> -p <PASSWORD>

Once logged in, Podman saves credentials under ~/.config/containers/auth.json, which your product can read for authenticated access.

For Local Podman API​

If your integration connects to Podman locally or remotely:

  1. Ensure Podman API service is active:
   systemctl --user enable --now podman.socket
  1. The default Podman socket is located at:
   unix:///run/user/<UID>/podman/podman.sock
  1. Grant your application read-only or necessary permissions to this socket

Test Connectivity​

Local Podman Environment​

Use the following CLI commands to validate connectivity:

# List all containers
podman ps -a

# List all images
podman images

# Inspect a specific container
podman inspect <CONTAINER_ID>

# Get system info
podman info

Podman REST API (v4+)​

If your integration uses REST API:

curl --unix-socket /run/user/$UID/podman/podman.sock http://d/v4.0.0/libpod/containers/json

Remote Registry​

Verify authentication and registry listing:

podman search <image-name>
podman pull docker.io/library/nginx:latest
podman images

If these commands succeed, your credentials and permissions are configured properly.

Save the Results in the Platform and Create Connection​

  1. In your product's integration or connector setup, securely store:

    • REGISTRY_URL
    • REGISTRY_USERNAME
    • REGISTRY_ACCESS_TOKEN (or password)
    • PODMAN_SOCKET_PATH (for local integrations)

  2. For local integrations, ensure your platform connects to the Podman API socket with the correct permissions

  3. Test the integration by listing images or container instances

Best Practices​

  • Use read-only registry credentials to avoid unintentional image modifications
  • Avoid storing raw credentials in plain text — use encrypted secrets management
  • Regularly rotate access tokens for registries like Docker Hub, Quay.io, or Red Hat registries
  • If integrating locally, run your product under the same user session that owns the Podman socket
  • Use Podman REST API v4+ for scalable, secure integrations (preferred over CLI parsing)
  • Enable audit logging for Podman API calls to track container actions in enterprise setups
  • For enterprise environments, use Red Hat Quay or Podman Registry for secure image hosting with RBAC controls