grapsus-proxy 0.5.12

# Bundle Command

The `grapsus bundle` command manages the installation of bundled agents - a curated set of agents that are tested to work together with a specific version of Grapsus.

## Overview

Instead of manually downloading and configuring each agent, the bundle command:

1. Reads a version lock file that pins compatible agent versions
2. Downloads agents from their respective GitHub releases
3. Installs binaries to the appropriate locations
4. Optionally generates configuration and systemd service files

## Quick Start

```bash
# Install Grapsus first
curl -fsSL https://get.grapsusproxy.io | sh

# Install all bundled agents
sudo grapsus bundle install

# Check what's installed
grapsus bundle status

# Start everything
sudo systemctl start grapsus.target
```

## Commands

### `grapsus bundle install`

Downloads and installs bundled agents.

```bash
# Install all agents
grapsus bundle install

# Install a specific agent
grapsus bundle install waf

# Preview without installing
grapsus bundle install --dry-run

# Force reinstall
grapsus bundle install --force

# Include systemd services
grapsus bundle install --systemd

# Custom installation prefix
grapsus bundle install --prefix /opt/grapsus
```

**Options:**

| Option | Description |
|--------|-------------|
| `--dry-run, -n` | Preview what would be installed |
| `--force, -f` | Reinstall even if already up to date |
| `--systemd` | Also install systemd service files |
| `--prefix PATH` | Custom installation prefix |
| `--skip-verify` | Skip SHA256 checksum verification |

### `grapsus bundle status`

Shows the installation status of all bundled agents.

```bash
grapsus bundle status
```

Example output:

```
Grapsus Bundle Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Bundle version: 26.01_1
Install path:   /usr/local/bin

Agent           Installed    Expected     Status
─────────────────────────────────────────────────
denylist        0.2.0        0.2.0        ✓ up to date
ratelimit       0.2.0        0.2.0        ✓ up to date
waf             -            0.2.0        ✗ not installed

Total: 3 | Up to date: 2 | Outdated: 0 | Not installed: 1
```

### `grapsus bundle list`

Lists available agents in the bundle.

```bash
grapsus bundle list
grapsus bundle list --verbose  # Show download URLs
```

### `grapsus bundle uninstall`

Removes installed agents.

```bash
# Uninstall all agents
grapsus bundle uninstall

# Uninstall a specific agent
grapsus bundle uninstall waf

# Preview
grapsus bundle uninstall --dry-run
```

### `grapsus bundle update`

Checks for available updates.

```bash
# Check for updates
grapsus bundle update

# Show and apply updates
grapsus bundle update --apply
```

## Bundled Agents

The bundle includes agents that cover ~80% of production use cases:

| Agent | Purpose |
|-------|---------|
| **waf** | ModSecurity-based Web Application Firewall |
| **ratelimit** | Token bucket rate limiting |
| **denylist** | IP and path blocking |

## Installation Paths

**System-wide (requires root):**
- Binaries: `/usr/local/bin/grapsus-{agent}-agent`
- Configs: `/etc/grapsus/agents/{agent}.yaml`
- Systemd: `/etc/systemd/system/grapsus-{agent}.service`

**User-local:**
- Binaries: `~/.local/bin/grapsus-{agent}-agent`
- Configs: `~/.config/grapsus/agents/{agent}.yaml`
- Systemd: `~/.config/systemd/user/grapsus-{agent}.service`

The command automatically detects whether to use system-wide or user-local paths based on permissions.

## Version Lock File

Agent versions are coordinated via `bundle-versions.lock`:

```toml
[bundle]
version = "26.01_1"

[agents]
waf = "0.2.0"
ratelimit = "0.2.0"
denylist = "0.2.0"

[repositories]
waf = "grapsusproxy/grapsus-agent-waf"
ratelimit = "grapsusproxy/grapsus-agent-ratelimit"
denylist = "grapsusproxy/grapsus-agent-denylist"
```

The lock file is embedded in the Grapsus binary at build time, ensuring reproducible installations.

## Configuration

After installation, configure agents in your `grapsus.kdl`:

```kdl
agents {
    agent "waf" {
        endpoint "unix:///var/run/grapsus/waf.sock"
        timeout-ms 100
        failure-mode "open"
    }

    agent "ratelimit" {
        endpoint "unix:///var/run/grapsus/ratelimit.sock"
        timeout-ms 50
        failure-mode "open"
    }

    agent "denylist" {
        endpoint "unix:///var/run/grapsus/denylist.sock"
        timeout-ms 20
        failure-mode "open"
    }
}
```

Then reference them in routes:

```kdl
routes {
    route "api" {
        matches { path-prefix "/api" }
        upstream "backend"
        policies {
            agents "denylist" "ratelimit" "waf"
        }
    }
}
```

## Systemd Integration

With `--systemd`, the command installs service files and a target:

```bash
# Install with systemd
sudo grapsus bundle install --systemd

# Reload systemd
sudo systemctl daemon-reload

# Enable and start all services
sudo systemctl enable grapsus.target
sudo systemctl start grapsus.target

# Check status
sudo systemctl status grapsus.target
```

The `grapsus.target` starts the proxy and all agent services together.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    grapsus bundle                       │
│                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐ │
│  │   lock.rs   │───▶│  fetch.rs   │───▶│ install.rs  │ │
│  │ Parse lock  │    │  Download   │    │ Place files │ │
│  │   file      │    │  from GH    │    │ Set perms   │ │
│  └─────────────┘    └─────────────┘    └─────────────┘ │
│         │                  │                  │         │
│         ▼                  ▼                  ▼         │
│  bundle-versions     GitHub Releases    /usr/local/bin  │
│      .lock           (per agent)        /etc/grapsus   │
└─────────────────────────────────────────────────────────┘
```

## Troubleshooting

### Permission denied

Run with `sudo` for system-wide installation:

```bash
sudo grapsus bundle install
```

Or use user-local paths:

```bash
grapsus bundle install --prefix ~/.local
```

### Download failed

Check network connectivity and verify the agent release exists:

```bash
grapsus bundle list --verbose  # Shows download URLs
```

### Agent won't start

Check logs:

```bash
journalctl -u grapsus-waf -f
```

Verify socket permissions:

```bash
ls -la /var/run/grapsus/
```

### Version mismatch

Force reinstall:

```bash
sudo grapsus bundle install --force
```

## See Also

- [Agent Protocol](agents.md) - How agents communicate with the proxy
- [Configuration Reference](../../../config/docs/agents.md) - Agent configuration options
- [Deployment Guide](https://grapsusproxy.io/docs/deployment/grapsus-stack) - Full stack deployment