CyfroAgent and Setup

CyfroAgent is a lightweight daemon that performs asset inventory (processes, filesystems, local SBOM collection), exposes host telemetry and executes targeted scans and fetches secrets and misconfigurations during scheduled discovery.

This guide explains how to prepare, register, deploy, and verify CyfroAgent.

The CyfroAgent setup flow: prerequisites, a one-time registration token, and the generated Docker run command.

Accessing CyfroAgent

The page includes:

1. Setup prerequisites
2. One-time token generation
3. Install command template
4. Registered agent health list

Prerequisites

Before deployment, ensure all of the following are ready:

1. Active CyfroSec account and organization access.
2. At least one Account Group created.
3. Admin rights on the host where CyfroAgent will run.
4. Docker available on the target host (Docker Engine or Docker Desktop).
5. Outbound network access from the host to your CyfroSec deployment endpoints.

Recommended preparation:

1. Identify a clear agent name convention (for example: Linux_Prod_Server_2).
2. Decide on location labels used by your team.
3. Validate that the intended scan target path is readable when mounted.

Step 1: Select Account Group Scope

CyfroAgent registration is account-group scoped.

1. In the portal, select the target account group.
2. Open the CyfroAgent page.
3. Confirm that you are in the correct environment before generating tokens.

Step 2: Generate a Registration Token

From the CyfroAgent page:

1. Click Generate Token.
2. Copy the token immediately.
3. Use one token per agent deployment.

Token behavior:

1. Single-use by design.
2. Time-limited (the UI shows expiration).
3. Regenerate for each additional host.

Note: If token generation fails with permission errors, ensure you are using an administrator role with access to token creation.

Step 3: Generate a Fernet Key

From the CyfroAgent page, generate the Fernet encryption key that the agent uses to protect its stored credentials. Keep this key safe — it must remain the same across restarts.

Step 4: Run CyfroAgent (Docker)

Copy the docker command from the CyfroAgent tab of the CyfroSec portal after entering values for the requested parameters. A sample command has been provided below for which the parameter values have to be replaced:

docker run -d \
  --name cyfro-agent \
  --network host \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v cyfro-agent-data:/data/agent \
  -v /:/host:ro \
  cyfrosec/cyfro-agent:latest \
  --agentName "MyAgent" \
  --token "your-registration-token" \
  --fernet-key "your-fernet-key" \
  --location "MyLocation"

Step 5: Verify Agent Registration

A successful startup looks like:

Agent not registered, registering now...
Agent registered successfully.
Starting agent.
Performing initial backend synchronization...
Scheduler started with APScheduler

After agent startup:

1. Return to the CyfroAgent page.
2. Check the Registered Agents panel.
3. Confirm the agent appears with recent last-seen timestamp.

Typical status behavior:

If agent does not appear:

1. Verify token was unused and not expired
2. Confirm container started successfully
3. Check outbound network reachability
4. Generate a new token and redeploy

Managing the Agent

View logs:

docker logs -f cyfro-agent

Stop the agent:

docker stop cyfro-agent

Restart the agent:

docker restart cyfro-agent

Start the agent after a reboot (already registered):

docker start cyfro-agent

Re-register the agent — if you need to start fresh, remove the container and its data volume, then run again with a new token:

docker stop cyfro-agent && docker rm cyfro-agent
docker volume rm cyfro-agent-data

Then repeat Step 2 with a new registration token.

Updating to a New Image Version

If you already have the agent running with an older image and want to update to the latest version, follow these steps. Your credentials are preserved in the volume, so no re-registration is needed.

Step 1: Stop and remove the old container

docker stop cyfro-agent && docker rm cyfro-agent

Do not remove the cyfro-agent-data volume. It holds your agent credentials.

Step 2: Pull the latest image

docker pull cyfrosec/cyfro-agent:latest

Step 3: Run the agent with the new image

The agent will detect the existing credentials in the volume and skip registration automatically.

On a Linux server:

docker run -d \
  --name cyfro-agent \
  --network host \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v cyfro-agent-data:/data/agent \
  -v /path/to/your/code:/scan-target:ro \
  cyfrosec/cyfro-agent:latest

On macOS (local development):

docker run -d \
  --name cyfro-agent \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v cyfro-agent-data:/data/agent \
  -v /path/to/your/code:/scan-target:ro \
  cyfrosec/cyfro-agent:latest

Note: macOS does not support --network host. The agent will use Docker's default bridge network instead.

Step 4: Verify the update

docker logs -f cyfro-agent

You should see:

Agent already registered. Skipping registration.
Starting agent.
Performing initial backend synchronization...
Scheduler started with APScheduler

Important Notes

1. Do not delete the cyfro-agent-data volume unless you intend to re-register. It contains the agent's encrypted credentials.
2. The CYFRO_FERNET_KEY must remain the same across restarts. Changing it will require re-registration.
3. Registration tokens are one-time use. Contact CyfroSec for a new token if needed.
4. The agent runs scans periodically in the background. No manual intervention is required after setup.

Integration with Scans

CyfroAgent is required for scheduled scan execution.

Before creating scans, ensure at least one agent is registered in the target account group.

Verification Checklist

1. Docker running on host.
2. Token copied exactly and still valid.
3. Correct account group context selected before token generation.
4. Host can reach CyfroSec endpoints.
5. Container logs show successful startup and registration.
6. Agent appears in CyfroAgent page and then in Agent Status widgets.

Frequently Asked Questions about CyfroAgent

Can one token register multiple agents? No. Tokens are single-use.

Can I regenerate tokens any time? Yes. Generate a fresh token for each new deployment.

Why is my agent listed as Offline? Most commonly heartbeat delay, network interruption, or container stop/crash.

Do I need an account group before deploying? Yes. Registration is scoped to an account group.