> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ayliea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Collector

> Deploy the Ayliea Collector to discover AI platform usage through DNS and TLS traffic analysis.

## Overview

The Ayliea Collector is a lightweight network agent that passively discovers AI platform usage on your network. It captures DNS queries and TLS Server Name Indication (SNI) handshakes — both plaintext metadata — and forwards matched events to Ayliea for analysis.

**Privacy-first by design:**

* No SSL/TLS decryption
* No packet payload inspection
* No content analysis
* No endpoint agents required

The collector ships with a built-in registry of 57+ AI platforms and 177+ domains, covering LLM providers, code assistants, image generators, and enterprise AI services.

## Deployment Methods

Choose the method that fits your environment:

<CardGroup cols={3}>
  <Card title="Docker" icon="docker" href="#docker">
    Recommended for most deployments. Hardened container with minimal privileges.
  </Card>

  <Card title="Static Binary" icon="terminal" href="#static-binary">
    Self-contained binary for hosts without Docker. Linux x86\_64 and ARM64.
  </Card>

  <Card title="Syslog Forwarding" icon="arrows-rotate" href="#syslog-forwarding">
    Point your existing firewall syslog at Ayliea. No agent required.
  </Card>
</CardGroup>

## Prerequisites

Before deploying, generate a monitoring token in Ayliea:

<Steps>
  <Step title="Navigate to Discovery">
    Go to **Discovery** in the left sidebar of your Ayliea dashboard.
  </Step>

  <Step title="Generate a token">
    In the **Monitoring Tokens** section, click **Generate Token** and enter a descriptive label (e.g., "prod-firewall" or "hq-network").
  </Step>

  <Step title="Save the token">
    Copy the token immediately — it is shown only once. You will need it for all deployment methods.
  </Step>
</Steps>

<Warning>
  Monitoring tokens are shown once at creation. If you lose a token, revoke it and generate a new one.
</Warning>

## Docker

The recommended deployment method. The container runs as a non-root user with a read-only filesystem and minimal Linux capabilities.

<Steps>
  <Step title="Create the compose file">
    Save the following as `docker-compose.collector.yml`:

    ```yaml docker-compose.collector.yml theme={null}
    services:
      ayliea-collector:
        image: ghcr.io/ayliea/ayliea-collector:latest
        container_name: ayliea-collector
        network_mode: host
        cap_drop:
          - ALL
        cap_add:
          - NET_RAW
        security_opt:
          - no-new-privileges:true
        read_only: true
        tmpfs:
          - /tmp:size=64m,noexec,nosuid
          - /run:size=16m,noexec,nosuid
        deploy:
          resources:
            limits:
              memory: 256m
              cpus: "1.0"
        environment:
          - AYLIEA_TOKEN=YOUR_TOKEN_HERE
          - AYLIEA_ENDPOINT=ingest.ayliea.com
          - INTERFACE=eth0
          - SYSLOG_PORT=6514
          - SYSLOG_PROTOCOL=tls
          - HTTPS_ENABLED=true
          - HEALTH_PORT=9090
          - LOG_LEVEL=INFO
        restart: unless-stopped
        logging:
          driver: json-file
          options:
            max-size: "10m"
            max-file: "3"
    ```

    Replace `YOUR_TOKEN_HERE` with your monitoring token and `eth0` with your network interface.
  </Step>

  <Step title="Find your network interface">
    ```bash theme={null}
    ip link show
    ```

    Common values: `eth0` (Linux), `ens33` (VMware), `eno1` (Dell/HP servers), `bond0` (bonded interfaces).
  </Step>

  <Step title="Start the collector">
    ```bash theme={null}
    docker compose -f docker-compose.collector.yml up -d
    ```
  </Step>

  <Step title="Verify it's running">
    ```bash theme={null}
    curl -s http://127.0.0.1:9090/health | python3 -m json.tool
    ```

    You should see `"status": "running"` and `events_captured` incrementing as traffic flows.
  </Step>
</Steps>

<Tip>
  If port 9090 is already in use on your host, change the `HEALTH_PORT` environment variable to an available port.
</Tip>

### Security hardening

The Docker configuration above includes production-grade security defaults:

| Setting                              | Purpose                                            |
| ------------------------------------ | -------------------------------------------------- |
| `cap_drop: ALL` + `cap_add: NET_RAW` | Only the packet capture capability is granted      |
| `read_only: true`                    | Container filesystem cannot be modified            |
| `no-new-privileges`                  | Prevents privilege escalation inside the container |
| `tmpfs` with `noexec,nosuid`         | Temp directories cannot execute binaries           |
| `memory: 256m`, `cpus: 1.0`          | Limits resource consumption                        |
| Non-root user                        | Container process does not run as root             |

### Environment variables

| Variable          | Default             | Description                                        |
| ----------------- | ------------------- | -------------------------------------------------- |
| `AYLIEA_TOKEN`    | *(required)*        | Your organization's monitoring token               |
| `AYLIEA_ENDPOINT` | `ingest.ayliea.com` | Ingest endpoint hostname                           |
| `INTERFACE`       | `eth0`              | Network interface to capture on                    |
| `SYSLOG_PORT`     | `6514`              | Syslog forwarding port                             |
| `SYSLOG_PROTOCOL` | `tls`               | Transport protocol: `tls`, `tcp`, or `udp`         |
| `HTTPS_ENABLED`   | `true`              | Enable HTTPS batch forwarding                      |
| `HEALTH_PORT`     | `9090`              | Local health endpoint port                         |
| `LOG_LEVEL`       | `INFO`              | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |

## Static Binary

A self-contained binary for Linux hosts without Docker. No Python runtime required — only `libpcap`.

<Steps>
  <Step title="Download and verify">
    Choose your architecture:

    | Platform      | Binary                         |
    | ------------- | ------------------------------ |
    | Linux x86\_64 | `ayliea-collector-linux-amd64` |
    | Linux ARM64   | `ayliea-collector-linux-arm64` |

    <Note>
      Run `uname -m` to check: `x86_64` = amd64, `aarch64` = arm64.
    </Note>

    ```bash theme={null}
    # Download binary and checksum
    curl -LO https://github.com/Ayliea/ayliea/releases/latest/download/ayliea-collector-linux-amd64
    curl -LO https://github.com/Ayliea/ayliea/releases/latest/download/ayliea-collector-linux-amd64.sha256

    # Verify integrity
    sha256sum -c ayliea-collector-linux-amd64.sha256

    # Make executable
    chmod +x ayliea-collector-linux-amd64
    ```
  </Step>

  <Step title="Install libpcap (if not present)">
    ```bash theme={null}
    # Debian/Ubuntu
    apt install libpcap0.8

    # RHEL/CentOS/Fedora
    yum install libpcap
    ```

    Most server distributions include `libpcap` by default.
  </Step>

  <Step title="Run the collector">
    ```bash theme={null}
    sudo ./ayliea-collector-linux-amd64 \
      --token YOUR_TOKEN \
      --interface eth0
    ```

    The binary requires root or `CAP_NET_RAW` for packet capture.
  </Step>
</Steps>

### CLI options

All options can also be set via environment variables. CLI flags take precedence.

```
ayliea-collector [OPTIONS]

Options:
  --token TOKEN              Ingest token (env: AYLIEA_TOKEN)
  --interface IFACE          Network interface (env: INTERFACE, default: eth0)
  --endpoint HOST            Ingest hostname (env: AYLIEA_ENDPOINT, default: ingest.ayliea.com)
  --syslog-port PORT         Syslog port (env: SYSLOG_PORT, default: 6514)
  --syslog-protocol PROTO    tls | tcp | udp (env: SYSLOG_PROTOCOL, default: tls)
  --no-https                 Disable HTTPS batch forwarding (env: HTTPS_ENABLED=false)
  --log-level LEVEL          DEBUG | INFO | WARNING | ERROR (env: LOG_LEVEL, default: INFO)
```

### Running as a systemd service

For persistent deployments, create a systemd unit:

```ini /etc/systemd/system/ayliea-collector.service theme={null}
[Unit]
Description=Ayliea Collector
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ayliea-collector --token YOUR_TOKEN --interface eth0
Restart=on-failure
RestartSec=10
AmbientCapabilities=CAP_NET_RAW
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
User=ayliea-collector

[Install]
WantedBy=multi-user.target
```

```bash theme={null}
# Create service user
sudo useradd -r -s /usr/sbin/nologin ayliea-collector

# Copy binary
sudo cp ayliea-collector-linux-amd64 /usr/local/bin/ayliea-collector

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now ayliea-collector
```

## Syslog Forwarding

If your firewall or proxy already exports syslog, you can point it directly at Ayliea without deploying an agent.

### Ingest endpoints

| Protocol          | Endpoint            | Port |
| ----------------- | ------------------- | ---- |
| TLS (recommended) | `ingest.ayliea.com` | 6514 |
| TCP               | `ingest.ayliea.com` | 514  |
| UDP               | `ingest.ayliea.com` | 514  |

### Authentication

Include your monitoring token in the RFC 5424 structured data element on every syslog message:

```
[ayliea@00000 key="YOUR_TOKEN"]
```

Most enterprise firewalls (Palo Alto, Fortinet, pfSense) support custom structured data in their syslog forwarding configuration.

### Supported log formats

| Vendor             | Format                                   | Notes           |
| ------------------ | ---------------------------------------- | --------------- |
| Palo Alto Networks | CSV traffic/URL filtering logs           | Auto-detected   |
| FortiGate          | Key=value syslog or CSV export           | Auto-detected   |
| pfSense / OPNsense | CSV export                               | Auto-detected   |
| Squid Proxy        | Native and CLF formats                   | Auto-detected   |
| Windows DNS Server | Debug log format                         | Auto-detected   |
| BIND               | Query log format                         | Auto-detected   |
| Zscaler            | CSV web log exports                      | Auto-detected   |
| Generic CSV        | Any CSV with domain/IP/timestamp columns | Fallback parser |

## Health Endpoint

Both the Docker container and the binary expose a local health endpoint (default: `http://127.0.0.1:9090/health`):

```json theme={null}
{
  "status": "running",
  "uptime_seconds": 3600,
  "interface": "eth0",
  "events_captured": 1542,
  "events_matched": 87,
  "platforms_detected": 12,
  "syslog_connected": true,
  "https_connected": true,
  "last_event_at": "2026-04-10T21:15:48.230224+00:00"
}
```

Use this endpoint for monitoring and integration with your existing health check tooling (Uptime Kuma, Prometheus, etc.).

## Scan Frequency

The collector buffers captured events and processes them into discovery scans on a configurable schedule. You can set the scan frequency in your Ayliea dashboard under **Discovery > Scan Frequency**.

| Frequency           | Description                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **Hourly**          | Events processed every hour. Best for high-security environments needing rapid detection. |
| **Daily** (default) | Events processed once per day. Recommended for most organizations.                        |
| **Weekly**          | Events processed once per week. Suitable for low-traffic or cost-sensitive deployments.   |

Regardless of the schedule, events are processed immediately if the buffer reaches 5,000 events.

Events are persisted across collector restarts and deployments — no data is lost during planned maintenance.

## Troubleshooting

### No events captured

* Verify the interface name matches your primary network interface (`ip link show`)
* Confirm the container has `NET_RAW` capability: `docker inspect ayliea-collector | grep CapAdd`
* Check that DNS and TLS traffic is actually flowing on the specified interface
* Set `LOG_LEVEL=DEBUG` for verbose capture output

### Syslog forwarding errors

* Confirm `ingest.ayliea.com` resolves from the host: `dig ingest.ayliea.com`
* Check that port 6514 (TLS) or 514 (TCP/UDP) is not blocked by a firewall
* Verify your token is valid and has not been revoked
* Check your firewall's syslog forwarding logs for transmission errors

### Health endpoint unreachable

* The health endpoint binds to `127.0.0.1` — it is only accessible from the host itself
* If another service uses port 9090, set `HEALTH_PORT` to an unused port

### Connection verification timeout

After deploying, use the **Verify** button in the Ayliea dashboard to confirm events are flowing. If verification times out after 5 minutes:

* Generate test traffic by visiting an AI platform from a device on the monitored network (e.g., `curl https://api.openai.com`)
* Check the health endpoint for `events_captured > 0`
* Verify the token matches exactly (no extra spaces or quotes)