CyfroAgent and Setup

Accessing CyfroAgent

The page includes:

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

Prerequisites

Before deployment, ensure all of the following are ready:

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

Recommended preparation:

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

Step 1: Select Account Group Scope

CyfroAgent registration is account-group scoped.

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

Step 2: Generate a Registration Token

From the CyfroAgent page:

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

Token behavior:

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

Step: Generate a Fernet Key

From the CyfroAgent page:

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

Step 3: 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 \
  -v cyfro-agent-data:/data/agent \
  -v /path/to/your/code:/scan-target:ro \
  cyfrosec/cyfro-agent:latest \
  --agentName "MyAgent" \
  --token "your-registration-token" \
  --fernet-key "your-fernet-key" \
  --location "MyLocation"

Parameter

Step 4: Verify Agent Registration

docker logs -f cyfro-agent

A successful startup looks like:

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

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)

If the server reboots and the container is stopped, no re-registration is needed:

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

After Agent startup:

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

Typical status behavior:

If agent does not appear:

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

If you are still facing issues, please contact us at support@cyfrosec.com

Integration with Scans

CyfroAgent is required for scheduled test execution.

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

Verification Checklist

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

Frequently Asked Questions about CyfroAgent