Skip to content

exploopio/agent

Repository files navigation

Rediver Agent

Command-line security scanning agent that integrates with the Rediver platform.

Component Types

The Rediver platform supports four component types, all using the same agent binary:

Type Use Case Mode Description
Runner CI/CD One-shot Scans and exits, ideal for pipelines
Worker Production Daemon Server-controlled, polls for commands
Collector Infrastructure Daemon Gathers cloud/infra inventory
Platform Agent Shared Infra Daemon Multi-tenant shared agent with lease-based heartbeat

Choose your component type when creating an agent in the Rediver dashboard.

Platform Agent Mode (New)

Platform agents are shared infrastructure managed by Rediver operators, enabling tenants to use scan capacity without running their own agents:

# Register with bootstrap token (first time)
agent -platform -register \
  -bootstrap-token "rdv-bt-..." \
  -name "platform-agent-01" \
  -region "ap-southeast-1" \
  -capabilities "sast,sca,secret" \
  -max-jobs 5

# Run as platform agent (after registration)
agent -platform -daemon \
  -agent-id "..." \
  -agent-secret "..."

Key features:

  • Lease-based heartbeat - Renews every 30s, expires after 60s
  • Job polling - Long-poll for assigned jobs
  • Multi-tenant isolation - Each job runs in isolated context
  • Graceful drain - Finishes current jobs before shutdown
  • Workflow integration - Jobs can be triggered by automation workflows

Workflow-Triggered Jobs

Platform agents can receive jobs triggered by the Workflow Executor. These jobs include workflow context for correlation:

{
  "id": "job-123",
  "type": "scan",
  "tenant_id": "tenant-456",
  "workflow_context": {
    "workflow_id": "wf-789",
    "workflow_run_id": "run-abc",
    "trigger_type": "finding_created",
    "action_node_id": "node-xyz",
    "action_node_key": "run_deep_scan"
  }
}

The agent logs workflow context and echoes it back in job results for tracing.

Installation

Download Binary (Recommended)

Download the latest release from GitHub Releases:

# Linux (amd64)
curl -sSL https://github.com/exploopio/agent/releases/latest/download/agent_linux_amd64.tar.gz | tar xz
sudo mv agent /usr/local/bin/

# Linux (arm64)
curl -sSL https://github.com/exploopio/agent/releases/latest/download/agent_linux_arm64.tar.gz | tar xz
sudo mv agent /usr/local/bin/

# macOS (Apple Silicon)
curl -sSL https://github.com/exploopio/agent/releases/latest/download/agent_darwin_arm64.tar.gz | tar xz
sudo mv agent /usr/local/bin/

# macOS (Intel)
curl -sSL https://github.com/exploopio/agent/releases/latest/download/agent_darwin_amd64.tar.gz | tar xz
sudo mv agent /usr/local/bin/

Docker

docker pull exploopio/agent:latest   # Full (semgrep + gitleaks + trivy)
docker pull exploopio/agent:slim     # Minimal (no tools)
docker pull exploopio/agent:ci       # CI optimized (preloaded Trivy DB)

Go Install

go install github.com/exploopio/agent@latest

Quick Start

# Check available tools
agent -list-tools

# Check tool installation status
agent -check-tools

# Run a single scan
agent -tool semgrep -target ./src -verbose

# Run multiple scanners
agent -tools semgrep,gitleaks,trivy -target . -push

# Run in daemon mode (server-controlled)
agent -daemon -enable-commands -verbose

Deployment Modes

1. One-Shot Mode (CI/CD)

Run scan once and exit. Best for CI/CD pipelines.

export API_URL=https://api.exploop.io
export API_KEY=your-api-key
export AGENT_ID=your-agent-id

# Single tool
agent -tool semgrep -target . -push

# Multiple tools
agent -tools semgrep,gitleaks,trivy -target . -push

# With PR comments
agent -tools semgrep,gitleaks,trivy -target . -push -comments

2. Daemon Mode: Server-Controlled (Recommended)

Agent connects to server and waits for scan commands. Server tells the agent what to scan and when.

agent -daemon -enable-commands -verbose

3. Daemon Mode: Standalone

Agent scans local directories on a schedule.

agent -daemon -tools semgrep,gitleaks,trivy -target /path/to/code -push

4. Daemon Mode: Config File

Full configuration via YAML file.

agent -daemon -config agent.yaml

5. Platform Agent Mode

Run as a shared platform agent (K8s-inspired model):

# First-time registration with bootstrap token
agent -platform -register \
  -bootstrap-token "rdv-bt-..." \
  -name "platform-agent-01" \
  -region "ap-southeast-1" \
  -capabilities "sast,sca,secret" \
  -tools "semgrep,gitleaks,trivy" \
  -max-jobs 5

# Subsequent runs (credentials saved in ~/.exploop/platform-agent.json)
agent -platform -daemon

# Or with explicit credentials
agent -platform -daemon \
  -agent-id "uuid" \
  -agent-secret "secret"

Configuration

Environment Variables

Variable Required Description
API_URL Yes* Platform API URL
API_KEY Yes* API key for authentication
AGENT_ID No Agent identifier for tracking
REGION No Deployment region (e.g., us-east-1)
GITHUB_TOKEN Auto GitHub token (for PR comments)
GITLAB_TOKEN Auto GitLab token (for MR comments)

*Required when using -push flag or daemon mode

Platform Agent Environment Variables:

Variable Required Description
PLATFORM_AGENT_ID Yes** Platform agent UUID (after registration)
PLATFORM_AGENT_SECRET Yes** Platform agent secret (after registration)
BOOTSTRAP_TOKEN No Bootstrap token for initial registration
HEARTBEAT_INTERVAL No Heartbeat interval (default: 30s)
LEASE_DURATION No Lease duration in seconds (default: 60)
MAX_JOBS No Maximum concurrent jobs (default: 5)

**Required for platform agent mode

Config File (YAML)

# agent.yaml
agent:
  name: my-scanner
  region: ap-southeast-1
  enable_commands: true
  command_poll_interval: 30s
  heartbeat_interval: 1m

server:
  base_url: https://api.exploop.io
  api_key: your-api-key
  agent_id: your-agent-uuid

scanners:
  - name: semgrep
    enabled: true
    config:
      dataflow_traces: true  # Enable taint tracking (default)
  - name: gitleaks
    enabled: true
  - name: trivy-fs
    enabled: true

# Retry queue for network resilience
retry_queue:
  enabled: true
  interval: 5m
  max_attempts: 10

# Targets for standalone mode
targets:
  - /path/to/project1
  - /path/to/project2

Available Scanners

Tool Type Description
semgrep SAST Code analysis with dataflow/taint tracking
gitleaks Secret Secret and credential detection
trivy-fs SCA Filesystem vulnerability scanning
trivy-config IaC Infrastructure misconfiguration
trivy-image Container Container image scanning
trivy-full All vuln + misconfig + secret
nuclei DAST Vulnerability scanner

Data Flow Tracking

Semgrep scans automatically include dataflow traces (taint tracking) by default. This provides attack path visualization:

Source: user.go:25 → username := r.FormValue("username")
    ↓
Intermediate: user.go:30 → query := fmt.Sprintf("SELECT * WHERE name='%s'", username)
    ↓
Sink: user.go:35 → rows, _ := db.Query(query)

The output uses SARIF 2.1.0 codeFlows format, which is ingested into the platform's Data Flow Tracking feature.

Docker Deployment

Platform Agent Mode (Recommended for Shared Infrastructure)

# Register platform agent (first time)
docker run --rm \
  -v ~/.exploop:/root/.exploop \
  -e API_URL=https://api.exploop.io \
  -e BOOTSTRAP_TOKEN=rdv-bt-... \
  exploopio/agent:latest \
  -platform -register \
  -name "platform-agent-01" \
  -region "ap-southeast-1" \
  -capabilities "sast,sca,secret" \
  -max-jobs 5

# Run as platform agent daemon
docker run -d \
  --name exploop-platform-agent \
  --restart unless-stopped \
  -v ~/.exploop:/root/.exploop \
  -e API_URL=https://api.exploop.io \
  exploopio/agent:latest \
  -platform -daemon -verbose

Server-Controlled Mode (Tenant Agent)

docker run -d \
  --name exploop-agent \
  --restart unless-stopped \
  -e API_URL=https://api.exploop.io \
  -e API_KEY=your-api-key \
  -e AGENT_ID=your-agent-id \
  -e REGION=ap-southeast-1 \
  exploopio/agent:latest \
  -daemon -enable-commands -verbose

Standalone Mode

docker run -d \
  --name exploop-agent \
  --restart unless-stopped \
  -v /path/to/code:/code:ro \
  -e API_URL=https://api.exploop.io \
  -e API_KEY=your-api-key \
  -e AGENT_ID=your-agent-id \
  exploopio/agent:latest \
  -daemon -tools semgrep,gitleaks,trivy-fs -target /code -push

One-Shot Scan

docker run --rm \
  -v "$(pwd)":/code:ro \
  -e API_URL=https://api.exploop.io \
  -e API_KEY=your-api-key \
  exploopio/agent:latest \
  -tools semgrep,gitleaks,trivy-fs -target /code -push

Docker Compose

# docker-compose.yml
version: "3.8"
services:
  exploop-agent:
    image: exploopio/agent:latest
    container_name: exploop-agent
    restart: unless-stopped
    environment:
      - API_URL=https://api.exploop.io
      - API_KEY=${EXPLOOP_API_KEY}
      - AGENT_ID=${REDIVER_AGENT_ID}
      - REGION=ap-southeast-1
    command: ["-daemon", "-enable-commands", "-verbose"]

CI/CD Integration

GitHub Actions

# .github/workflows/security-scan.yml
name: Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Security Scan
        uses: docker://exploopio/agent:ci
        env:
          API_URL: ${{ secrets.EXPLOOP_API_URL }}
          API_KEY: ${{ secrets.EXPLOOP_API_KEY }}
          AGENT_ID: ${{ secrets.REDIVER_AGENT_ID }}
        with:
          args: -tools semgrep,gitleaks,trivy-fs -target . -push -comments

GitHub Actions (Binary)

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download Agent
        run: |
          curl -sSL https://github.com/exploopio/agent/releases/latest/download/agent_linux_amd64.tar.gz | tar xz
          chmod +x agent

      - name: Run Scan
        env:
          API_URL: ${{ secrets.EXPLOOP_API_URL }}
          API_KEY: ${{ secrets.EXPLOOP_API_KEY }}
          AGENT_ID: ${{ secrets.REDIVER_AGENT_ID }}
        run: ./agent -tools semgrep,gitleaks,trivy-fs -target . -push -comments

GitLab CI

# .gitlab-ci.yml
security-scan:
  stage: test
  image: exploopio/agent:ci
  variables:
    API_URL: $EXPLOOP_API_URL
    API_KEY: $EXPLOOP_API_KEY
    AGENT_ID: $REDIVER_AGENT_ID
  script:
    - agent -tools semgrep,gitleaks,trivy-fs -target . -push -comments
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Kubernetes Deployment

Secret

apiVersion: v1
kind: Secret
metadata:
  name: exploop-agent-secret
  namespace: security
type: Opaque
stringData:
  api-key: "your-api-key"

Deployment (Server-Controlled)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: exploop-agent
  namespace: security
spec:
  replicas: 1
  selector:
    matchLabels:
      app: exploop-agent
  template:
    metadata:
      labels:
        app: exploop-agent
    spec:
      containers:
        - name: agent
          image: exploopio/agent:latest
          args: ["-daemon", "-enable-commands", "-verbose"]
          env:
            - name: API_URL
              value: "https://api.exploop.io"
            - name: API_KEY
              valueFrom:
                secretKeyRef:
                  name: exploop-agent-secret
                  key: api-key
            - name: AGENT_ID
              value: "your-worker-id"
            - name: REGION
              value: "ap-southeast-1"
          resources:
            requests:
              memory: "256Mi"
              cpu: "100m"
            limits:
              memory: "1Gi"
              cpu: "1000m"

CronJob (Scheduled Scanning)

apiVersion: batch/v1
kind: CronJob
metadata:
  name: exploop-scan
  namespace: security
spec:
  schedule: "0 2 * * *"  # Daily at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: agent
              image: exploopio/agent:ci
              args:
                - "-tools"
                - "semgrep,gitleaks,trivy-fs"
                - "-target"
                - "/code"
                - "-push"
              env:
                - name: API_URL
                  value: "https://api.exploop.io"
                - name: API_KEY
                  valueFrom:
                    secretKeyRef:
                      name: exploop-agent-secret
                      key: api-key
              volumeMounts:
                - name: code
                  mountPath: /code
                  readOnly: true
          volumes:
            - name: code
              persistentVolumeClaim:
                claimName: source-code-pvc
          restartPolicy: OnFailure

Docker Images

Variant Description Use Case
latest All tools (semgrep, gitleaks, trivy) Production scanning
slim Agent only, no tools Custom tool setup
ci Full + preloaded Trivy DB CI/CD (faster startup)

SDK Dependency

This agent uses the Exploop SDK for:

  • Scanner implementations (Semgrep, Gitleaks, Trivy)
  • RIS format parsing and conversion
  • CI environment detection (GitHub, GitLab)
  • API client for pushing findings
  • Persistent retry queue for network resilience
# Update SDK
go get github.com/exploopio/sdk@latest && go mod tidy

Development

Prerequisites

  • Go 1.25+
  • Docker (for container builds)
  • golangci-lint (for linting)

Make Commands

make help              # Show all available commands
make build             # Build agent binary
make test              # Run tests
make lint              # Run golangci-lint
make docker            # Build full Docker image
make release-snapshot  # Build release locally (no publish)

Project Structure

agent/
├── main.go              # Main entry point
├── go.mod               # Go module definition
├── Makefile             # Build commands
├── Dockerfile           # Multi-target Docker build
├── .goreleaser.yaml     # GoReleaser config for releases
└── .github/workflows/
    ├── ci.yml           # CI pipeline
    ├── release.yml      # Binary releases
    └── docker-build.yml # Docker publish

Release Process

Releases are automated via GitHub Actions:

# Create and push a tag
git tag v0.2.0
git push origin v0.2.0

This triggers:

  • Binary builds for Linux/macOS/Windows (amd64/arm64)
  • Docker image builds and push to Docker Hub
  • Auto-generated changelog

💖 Support

If you find Rediver useful, please consider supporting the project:

BSC Network (BEP-20):

0x97f0891b4a682904a78e6Bc854a58819Ea972454

License

MIT License - See LICENSE file for details.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Packages

 
 
 

Contributors