Skip to content

README.md

Latest commit

 

History

History
259 lines (195 loc) · 8.68 KB

README.md

File metadata and controls

259 lines (195 loc) · 8.68 KB

Flashduty Runner

Go Lint Release Go Report Card License

English | 中文

Flashduty Runner is a lightweight, secure agent that runs in your environment to execute commands and access resources on behalf of Flashduty AI SRE platform.

How It Works

┌──────────────────┐       WebSocket (TLS)       ┌────────────────────┐
│  Flashduty AI    │ ◄─────────────────────────► │  Flashduty Runner  │
│  SRE Platform    │                             │  (Your Server)     │
└──────────────────┘                             └────────────────────┘
                                                          │
                                                          ▼
                                                 ┌────────────────────┐
                                                 │ • Execute Commands │
                                                 │ • Read/Write Files │
                                                 │ • MCP Tool Calls   │
                                                 └────────────────────┘

The runner establishes a persistent WebSocket connection to Flashduty cloud, receives task requests, executes them locally, and returns results.

Security

All code is open source - you can audit every line of code to verify exactly what the runner does.

Multi-layer Security Design

Layer Protection
Transport TLS-encrypted WebSocket, token authentication
Command Execution Shell parsing to prevent injection attacks (e.g., cmd1; cmd2)
Permission Control Configurable glob-based command whitelist/blacklist
File System Operations sandboxed to workspace root, symlink escape protection

Permission Configuration

The runner uses glob pattern matching for command permissions. You have full control over what commands can be executed.

Option 1: Strict Mode (Recommended for shared environments)

Only allow specific commands explicitly:

permission:
  bash:
    "*": "deny"                  # Deny all by default
    "kubectl get *": "allow"
    "kubectl describe *": "allow"
    "kubectl logs *": "allow"
    "cat *": "allow"
    "ls *": "allow"

Option 2: Trust Mode (For dedicated/isolated environments)

If the runner is deployed in an isolated environment dedicated to AI operations, you can choose to trust the AI model's judgment:

permission:
  bash:
    "*": "allow"                 # Trust AI model
    "rm -rf /": "deny"           # Block catastrophic commands if desired

This mode is suitable when:

  • The runner runs in an isolated VM/container with limited blast radius
  • You trust the AI model's capabilities and want maximum flexibility
  • Quick incident response is more important than restrictive permissions

Option 3: Read-Only Mode (For monitoring only)

permission:
  bash:
    "*": "deny"
    "cat *": "allow"
    "head *": "allow"
    "tail *": "allow"
    "ls *": "allow"
    "grep *": "allow"
    "ps *": "allow"
    "df *": "allow"
    "free *": "allow"

Quick Start

Binary Installation

# Linux (amd64)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Linux_x86_64.tar.gz
tar -xzf flashduty-runner_Linux_x86_64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

# Linux (arm64)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Linux_arm64.tar.gz
tar -xzf flashduty-runner_Linux_arm64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

# macOS (Apple Silicon)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Darwin_arm64.tar.gz
tar -xzf flashduty-runner_Darwin_arm64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

# macOS (Intel)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Darwin_x86_64.tar.gz
tar -xzf flashduty-runner_Darwin_x86_64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

Docker Installation

docker run -d \
  --name flashduty-runner \
  -e FLASHDUTY_RUNNER_TOKEN=wnt_xxx \
  -v /var/flashduty/workspace:/workspace \
  registry.flashcat.cloud/public/flashduty-runner:latest

# With custom endpoint
docker run -d \
  --name flashduty-runner \
  -e FLASHDUTY_RUNNER_TOKEN=wnt_xxx \
  -e FLASHDUTY_RUNNER_URL=wss://custom.example.com/safari/worknode/ws \
  -v /var/flashduty/workspace:/workspace \
  registry.flashcat.cloud/public/flashduty-runner:latest

Running

# Basic usage (token required)
flashduty-runner run --token wnt_xxx

# Specify workspace directory
flashduty-runner run --token wnt_xxx --workspace ~/projects

# Specify custom WebSocket endpoint
flashduty-runner run --token wnt_xxx --url wss://custom.example.com/safari/worknode/ws

# Check version
flashduty-runner version

Systemd Service (Linux)

Create /etc/systemd/system/flashduty-runner.service:

[Unit]
Description=Flashduty Runner
After=network.target

[Service]
Type=simple
User=flashduty
EnvironmentFile=/etc/flashduty-runner/env
ExecStart=/usr/local/bin/flashduty-runner run
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Create /etc/flashduty-runner/env:

FLASHDUTY_RUNNER_TOKEN=wnt_xxx
# FLASHDUTY_RUNNER_URL=wss://custom.example.com/safari/worknode/ws
# FLASHDUTY_RUNNER_WORKSPACE=/var/flashduty/workspace
sudo mkdir -p /etc/flashduty-runner
sudo vim /etc/flashduty-runner/env   # add your token
sudo systemctl daemon-reload
sudo systemctl enable --now flashduty-runner

Configuration Reference

Configuration is via command-line flags or environment variables (flags take precedence).

Flag Env Variable Required Default Description
--token FLASHDUTY_RUNNER_TOKEN Yes - Authentication token
--url FLASHDUTY_RUNNER_URL No wss://api.flashcat.cloud/safari/worknode/ws WebSocket endpoint
--workspace FLASHDUTY_RUNNER_WORKSPACE No ~/.flashduty-runner/workspace Workspace root directory
--log-level FLASHDUTY_RUNNER_LOG_LEVEL No info Log level: debug, info, warn, error

Troubleshooting

Connection Issues

Symptom Cause Solution
failed to connect Network issue Check firewall allows outbound port 443
authentication failed Invalid token Verify token in Flashduty console
Runner not showing online Connection dropped Check logs, verify token matches account 
# Test connectivity
curl -v https://api.flashcat.cloud/health

# Check runner logs
journalctl -u flashduty-runner -f

Permission Issues

Symptom Cause Solution
command denied Command not in whitelist Add pattern to permission.bash
path escapes workspace Path traversal blocked Use paths within workspace_root

Permission Pattern Rules:

  • Patterns are matched in order, last match wins
  • * matches any characters
  • Empty config defaults to deny all

Debug Mode

Enable debug logging to see detailed permission decisions:

flashduty-runner run --token wnt_xxx --log-level debug

# Or via environment variable
export FLASHDUTY_RUNNER_LOG_LEVEL=debug

Contributing

We welcome contributions! Please see CONTRIBUTING.md.

License

Apache License 2.0 - see LICENSE.

Made with ❤️ by Flashcat