Skip to main content

🔐 Garnet Token

Jibril requires a Garnet API token to operate. This guide shows you how to obtain and configure your token.

🔑 Getting Your Token​

Step 1: Access Garnet Dashboard​

Visit: https://dashboard.garnet.ai

Create an account if you don't have one.

Step 2: Create Project Token​

  1. Navigate to Settings → API Tokens
  2. Click Create Token
  3. Select Permissions for the token
  4. Give it a descriptive name (e.g., "jibril-poc")
  5. Click Create
  6. Copy the token and keep it safe

⚠️ Security Warning

  • Store your token securely (password manager, secrets vault)
  • Never commit tokens to version control
  • Create separate tokens per environment (dev/staging/prod)
  • Rotate tokens periodically

⚙️ Configuring the Token​

Choose one of three methods:

Best for: Cloud deployments, CI/CD, containerized environments

export GARNET_API_TOKEN=your-token-here

Then run Jibril:

sudo -E jibril --config /etc/jibril/config.yaml

Advantages:

  • Easy to rotate without modifying configuration files
  • Environment-specific (different tokens for dev/staging/prod)
  • Works well with secret management systems
  • No risk of committing to version control

Method 2: Configuration File​

Best for: Traditional server deployments, persistent configuration

# /etc/jibril/config.yaml
run-time:
  api:
    token: your-token-here

Advantages:

  • Persistent across reboots
  • Clear, documented configuration

Important: Secure the configuration file:

sudo chmod 600 /etc/jibril/config.yaml
sudo chown root:root /etc/jibril/config.yaml

Method 3: Systemd Environment File​

Best for: Systemd service deployments

# Create secure environment file
sudo mkdir -p /etc/default
sudo tee /etc/default/jibril << EOF
GARNET_API_TOKEN=your-token-here
EOF

# Secure the file
sudo chmod 600 /etc/default/jibril
sudo chown root:root /etc/default/jibril

The systemd service will automatically load this file on start.

Advantages:

  • Systemd-native approach
  • Separated from main configuration
  • Automatically loaded on service start

🚀 First Start​

When you start Jibril with a valid token for the first time:

  1. Jibril registers with Garnet API
  2. An agent-specific token is generated and stored in /var/lib/jibril/agent.token
  3. Jibril starts normally
sudo jibril --config /etc/jibril/config.yaml

Expected log output:

INFO: detected runtime environment: vanilla
INFO: agent registration complete
INFO: agent kind: vanilla
INFO: token stored at: /var/lib/jibril/agent.token

ℹ️ Project Token vs Agent Token

  • Project Token (you configure) - Used during initial registration
  • Agent Token (auto-generated) - Stored in /var/lib/jibril/agent.token, used for ongoing operations

After first start, the agent token is used automatically. The project token is only needed again if you delete the agent token file or move to a different machine.

📊 Optional: Garnet Dashboard Integration​

Once your agent is registered (which happens automatically with a valid token), you can optionally enable the Garnet printer to send security events to the centralized Garnet Dashboard.

ℹ️ Agent Registration vs Event Dashboard

  • Agent Registration (required) - Uses API token, allows Jibril to run
  • Garnet Printer (optional) - Sends security events to dashboard for visualization

You can run Jibril with only local printers (stdout, file) and skip the dashboard integration.

Enabling Garnet Printer​

To send events to the dashboard, add the garnet printer to your configuration:

# /etc/jibril/config.yaml
printers:
  - stdout        # Local output
  - garnet        # Dashboard integration (optional)

Dashboard provides:

  • 📊 Centralized event aggregation across all agents
  • 🔍 Real-time event search and filtering
  • 📈 Security analytics and trend visualization
  • 🚨 Alert management and notifications
  • 🤖 AI-powered threat analysis

Use cases:

  • Quick environment overview without complex SIEM setup
  • Centralized monitoring across multiple servers/clusters
  • Rapid security incident investigation
  • Alternative to integrating with Wazuh, Grafana, or other tools

💡 Note: You can use both local printers AND the Garnet printer simultaneously for redundancy.

❌ Starting Without a Token​

If you try to start Jibril without configuring a token, you'll see this error:

error: GARNET_API_TOKEN is required

Please create a project API token at:
https://dashboard.garnet.ai/dashboard/settings?tab=tokens

Then set it via one of these methods:

1. Environment variable:
     export GARNET_API_TOKEN=your-token-here

2. Configuration file (/etc/jibril/config.yaml):
     run-time:
       api:
         token: your-token-here

3. Systemd environment file (/etc/default/jibril):
     GARNET_API_TOKEN=your-token-here

Jibril will not start without a valid token.

🔄 Re-registration​

To re-register an agent (e.g., moving to a new machine, testing):

# Remove existing agent token
sudo rm /var/lib/jibril/agent.token

# Restart Jibril (will re-register using project token)
sudo systemctl restart jibril

The agents can be deleted from the dashboard, and will be re-registered automatically when Jibril starts with a valid token.

🌐 Advanced Configuration​

Custom API Endpoint​

For self-hosted or on-premise Garnet installations:

Via configuration file:

run-time:
  api:
    url: https://your-garnet-instance.com/
    token: your-token-here

Via environment variables:

export GARNET_API_URL=https://your-garnet-instance.com/
export GARNET_API_TOKEN=your-token-here

Custom Agent Token Storage Path​

run-time:
  api:
    agent-token-path: /custom/path/agent.token

Verify Successful Registration​

Check if registration completed successfully:

# Check logs for registration success
sudo journalctl -u jibril | grep "agent registration complete"

# Verify agent token file was created
sudo ls -la /var/lib/jibril/agent.token

# Should show: -rw------- 1 root root ... agent.token

🔐 Security Best Practices​

✅ Do​

  • ✅ Use environment variables for token storage
  • ✅ Create separate tokens for each environment
  • ✅ Store tokens in secret management systems (Vault, AWS Secrets Manager, etc.)
  • ✅ Rotate tokens regularly (e.g., every 90 days)
  • ✅ Use descriptive names for tokens in dashboard
  • ✅ Revoke tokens immediately if compromised
  • ✅ Review token usage in Garnet Dashboard periodically

❌ Don't​

  • ❌ Commit tokens to git repositories
  • ❌ Share tokens across teams or projects
  • ❌ Use production tokens in development/test
  • ❌ Hardcode tokens in scripts or automation
  • ❌ Leave tokens in command history
  • ❌ Store tokens in unencrypted files
  • ❌ Use the same token across all environments

🚀 Next Steps​

Once your token is configured, proceed with installation: