### Set up QEMU for Cross-Architecture Builds

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Install QEMU user-mode emulation support on your x86_64 system to enable building ARM64 images. This is a one-time setup.

```bash
# Install QEMU support (one-time)
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# Then build normally
cd 8.0
./build.sh
```

--------------------------------

### Setup DNF Repositories

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Configures the DNF package manager by updating packages, installing EPEL and DNF plugins, and enabling the CodeReady Builder repository.

```dockerfile
RUN dnf -y update && \
    dnf -y install epel-release dnf-plugins-core && \
    dnf config-manager --set-enabled crb
```

--------------------------------

### Build Script Usage Examples

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-system.md

Examples demonstrating common build scenarios, including default builds, specific architecture/variant selection, and options for pushing and manifest creation.

```bash
# Build both architectures, both variants (default)
./build.sh
```

```bash
# Build only amd64, regular variant
./build.sh --arch amd64 --variant regular
```

```bash
# Build, push, and create manifest
./build.sh --push --manifest
```

```bash
# Build multiple architectures selectively
./build.sh --arch amd64 --arch arm64
```

```bash
# Skip Docker builds, only create/push manifests
./build.sh --no-build --manifest
```

--------------------------------

### PCAP File Analysis Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

An example for analyzing a PCAP file. This setup does not require special capabilities and mounts local directories for PCAP input and log output.

```bash
docker run --rm -it \
    -v $(pwd)/pcaps:/pcaps \
    -v $(pwd)/logs:/var/log/suricata \
    jasonish/suricata:latest -r /pcaps/capture.pcap -l /var/log/suricata
```

--------------------------------

### Execute External Commands Examples

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Examples demonstrating how to run external commands using the command passthrough feature of the entrypoint script.

```bash
docker run jasonish/suricata:latest suricata-update -f
```

```bash
docker run jasonish/suricata:latest /bin/bash
```

```bash
docker run jasonish/suricata:latest echo "hello"
```

--------------------------------

### Complete Multi-Volume Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

A comprehensive example demonstrating the mounting of configuration, logs, and data directories for Suricata in Docker. It also includes necessary capabilities for network operations.

```bash
mkdir -p etc logs data
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/etc:/etc/suricata \
    -v $(pwd)/logs:/var/log/suricata \
    -v $(pwd)/data:/var/lib/suricata \
    -e PUID=$(id -u) -e PGID=$(id -g) \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Install Suricata and Configuration Files

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Installs Suricata binaries, libraries, and default configuration files into a temporary fakeroot directory.

```dockerfile
RUN make install install-conf DESTDIR=/fakeroot
```

--------------------------------

### Start Suricata Container

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Start the Suricata container with host networking and necessary capabilities. This is the first step to running Suricata-Update.

```bash
docker run --name=suricata --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Build Script Initialization

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Example of variable initialization at the beginning of the build script.

```bash
VERSION=$(cat VERSION)
DOCKER=docker
CORES=$(nproc --all)
MAJOR=$(basename $(pwd))
LATEST=$(cat ../LATEST)

```

--------------------------------

### Basic Live Capture Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

A complete example for basic live capture, including automatic removal, interactive mode, host networking, necessary capabilities, log volume, and interface specification.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Docker Compose Deployment Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/MANIFEST.txt

Example configuration for deploying Suricata using Docker Compose. This snippet shows a basic service definition.

```yaml
services:
  suricata:
    image: jasonish/suricata
    container_name: suricata
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - ./suricata.logrotate:/etc/logrotate.d/suricata.logrotate
      - ./update.yaml:/etc/suricata/update.yaml
      - ./suricata.yaml:/etc/suricata/suricata.yaml
    ports:
      - "80:80"
    restart: unless-stopped
```

--------------------------------

### Live Capture with Persistent Configuration and Data

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

An example demonstrating live capture with persistent storage for configuration, logs, and data using bind mounts.

```bash
mkdir -p etc logs data
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/etc:/etc/suricata \
    -v $(pwd)/logs:/var/log/suricata \
    -v $(pwd)/data:/var/lib/suricata \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Kubernetes DaemonSet Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/MANIFEST.txt

Example DaemonSet definition for deploying Suricata on Kubernetes. This snippet shows how to configure host volumes, capabilities, and image for a DaemonSet.

```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: suricata
  labels:
    app: suricata
spec:
  selector:
    matchLabels:
      app: suricata
  template:
    metadata:
      labels:
        app: suricata
    spec:
      hostNetwork: true
      dnsPolicy: ClusterFirstWithHostNet
      containers:
        - name: suricata
          image: jasonish/suricata
          securityContext:
            privileged: true
            capabilities:
              add: ["NET_ADMIN", "NET_RAW"]
          volumeMounts:
            - name: suricata-config
              mountPath: /etc/suricata
            - name: suricata-logs
              mountPath: /var/log/suricata
      volumes:
        - name: suricata-config
          hostPath:
            path: /etc/suricata
        - name: suricata-logs
          hostPath:
            path: /var/log/suricata
```

--------------------------------

### Dockerfile CONFIGURE_ARGS Argument Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Demonstrates the use of the CONFIGURE_ARGS build argument for passing flags to Suricata's configure script.

```dockerfile
ARG CONFIGURE_ARGS
RUN ./configure \
        ... \
        ${CONFIGURE_ARGS}

```

--------------------------------

### Docker Compose Management Commands

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Common commands for managing the Suricata Docker Compose setup. Use these to start, view logs, update rules, and stop the Suricata container.

```bash
docker-compose up -d          # Start
```

```bash
docker-compose logs -f        # View logs
```

```bash
docker-compose exec suricata suricata-update -f  # Update rules
```

```bash
docker-compose down           # Stop
```

--------------------------------

### Suricata Version File Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/module-architecture.md

Indicates the specific version of Suricata to be downloaded and built. Different version directories contain their respective VERSION files.

```text
7.0.15
```

```text
8.0.4
```

```text
main
```

--------------------------------

### Dockerfile VERSION Argument Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Illustrates how the VERSION build argument is used in the Dockerfile to determine source acquisition.

```dockerfile
ARG VERSION
RUN if [ "${VERSION}" = "main" ]; then
        git clone ...
    else
        curl -OL https://www.openinfosecfoundation.org/download/suricata-${VERSION}.tar.gz
fi

```

--------------------------------

### Systemd Service Unit Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/MANIFEST.txt

Example systemd service unit file for running Suricata as a system service. This snippet defines the service's execution, dependencies, and restart behavior.

```ini
[Unit]
Description=Suricata Intrusion Detection System
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/suricata -c /etc/suricata/suricata.yaml -i eth0
Restart=on-failure

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

--------------------------------

### Dockerfile CORES Argument Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Shows how the CORES build argument is used for parallel compilation in the Dockerfile.

```dockerfile
ARG CORES=2
RUN make -j "${CORES}"

```

--------------------------------

### Install Runtime Dependencies

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Installs necessary runtime packages for Suricata, including libraries and utilities. Cleans up package manager cache and unnecessary logrotate configurations.

```dockerfile
RUN dnf -y install \
        cronie \
        dpdk \
        elfutils-libelf \
        file \
        findutils \
        hiredis \
        iproute \
        jansson \
        libbpf \
        libyaml \
        libnfnetlink \
        libnetfilter_queue \
        libnet \
        libcap-ng \
        libevent \
        libmaxminddb \
        libpcap \
        libprelude \
        logrotate \
        lz4 \
        net-tools \
        numactl \
        pcre2 \
        procps-ng \
        python3 \
        python3-yaml \
        tcpdump \
        which \
        zlib && \
        if [ "$(arch)" = "x86_64" ]; then dnf -y install hyperscan; fi && \
        dnf clean all && \
        find /etc/logrotate.d -type f -not -name suricata -delete
```

--------------------------------

### Start Suricata Container with a Name for Volume Sharing

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Start the Suricata container with a specific name to allow other containers to access its volumes.

```bash
docker run -it --net=host --name=suricata jasonish/suricata -i enp3s0
```

--------------------------------

### Install x86_64 Hyperscan Development Headers

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Conditionally installs the Hyperscan development headers if the architecture is x86_64. Hyperscan is used for pattern matching.

```dockerfile
RUN if [ "$(arch)" = "x86_64" ]; then \
    dnf -y install hyperscan-devel; \
fi
```

--------------------------------

### Build Script Argument Parsing

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Example of argument parsing within the main build script.

```bash
while [ "$#" -gt 0 ]; do
    case "${key}" in
        --push) PUSH="yes" ;;
        --manifest) MANIFEST="yes" ;;
        --no-build) BUILD="no" ;;
        --no-cache) NOCACHE="--no-cache" ;;
        --arch) ARCHES+=("$1"); shift ;;
        --variant) VARIANT="$1"; shift ;;
    esac
    shift
done

```

--------------------------------

### Docker Swarm Service Definition Example

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/MANIFEST.txt

Example service definition for deploying Suricata in a Docker Swarm environment. This snippet illustrates how to configure capabilities and volumes for a Swarm service.

```yaml
deploy:
  mode: global
  restart_policy:
    condition: unless-stopped
  resources:
    limits:
      cpus: '0.50'
      memory: 512M
    reservations:
      cpus: '0.25'
      memory: 256M
  placement:
    constraints: []
  update_config:
    parallelism: 1
    delay: 10s
    order: start-first
    max_failure_ratio: 0
  rollback_config:
    parallelism: 1
    delay: 10s
    order: start-first
    max_failure_ratio: 0
  # ... other deploy options
```

--------------------------------

### Start Logstash Container Sharing Volumes

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

Starts a Logstash container, sharing volumes with the Suricata container and mounting a custom configuration directory.

```bash
docker run --volumes-from=suricata \
    -v /etc/logstash/conf.d:/config \
    docker.elastic.co/logstash/logstash:latest
```

--------------------------------

### Docker Authentication Commands

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Provides example commands for logging into Docker registries. Authentication is assumed to be pre-configured before running the build script.

```bash
# Docker Hub (default)
docker login docker.io

# Quay.io
docker login quay.io
```

--------------------------------

### Monitor Interface with Host Capabilities

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Example of running the Suricata container to monitor a network interface using host networking and specific capabilities. Requires root privileges.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Version File Content

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Examples of the VERSION file content for different Suricata branches.

```text
7.0.15

```

```text
8.0.4

```

```text
main

```

--------------------------------

### Suricata + JSON Parser Multi-Container Setup

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Demonstrates running a JSON parser (like jq) in a separate container that shares the Suricata logs volume. This allows for processing Suricata's eve.json output.

```bash
# Start Suricata
docker run -d --name=suricata --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
    jasonish/suricata:latest -i eth0

# Process logs from another container
docker run -it --volumes-from=suricata \
    jq . < /var/log/suricata/eve.json

# Or continuously tail
docker exec -it suricata tail -f /var/log/suricata/eve.json | jq .
```

--------------------------------

### Systemd Service Management Commands

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Commands to enable, start, and view logs for the Suricata systemd service.

```bash
sudo systemctl enable suricata
sudo systemctl start suricata
sudo systemctl logs -u suricata
```

--------------------------------

### Run with Custom UID/GID for Bind Mounts

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Example of running the Suricata container with custom user and group IDs to ensure compatibility with bind mounts. This is useful for managing file permissions.

```bash
docker run -e PUID=$(id -u) -e PGID=$(id -g) \
    -v $(pwd)/etc:/etc/suricata \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Monitor Multiple Interfaces

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Examples of configuring Suricata to monitor multiple network interfaces simultaneously. This can be done by listing interfaces explicitly or using the 'any' keyword if supported.

```bash
docker run --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i eth0 -i eth1 -i eth2

Or use `any` (if supported):
docker run --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i any
```

--------------------------------

### Run a Different Command (suricata-update)

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Example of executing a different command within the running Suricata container, such as `suricata-update`, using `docker exec`. This is useful for managing Suricata's rulesets.

```bash
docker exec -it suricata suricata-update -f
```

--------------------------------

### Enable Cron Daemon

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Starts the cron daemon if the ENABLE_CRON environment variable is set to 'yes'. This is useful for scheduled tasks like log rotation.

```bash
if [[ "$ENABLE_CRON" == "yes" ]]; then
    crond
fi
```

--------------------------------

### Interactive Suricata Troubleshooting

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Starts a Suricata Docker container in interactive mode with a bash shell. This allows for direct execution of Suricata and Suricata-Update commands inside the container for troubleshooting.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/etc:/etc/suricata \
    jasonish/suricata:latest bash

# Inside container:
root@container# suricata --build-info
root@container# suricata-update list-sources
root@container# suricata -i eth0 -vvv
```

--------------------------------

### Start Suricata Container

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

Launches a Suricata container in detached mode, sharing the host's network, with necessary capabilities, and mounting a local logs directory.

```bash
docker run -d --name=suricata --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Pulling Docker Images from Different Registries

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/image-tags-and-versioning.md

Examples of pulling Docker Suricata images using the 'latest', version-specific, and architecture-specific tags from Docker Hub, Quay.io, and GitHub Container Registry.

```bash
docker pull jasonish/suricata:latest
docker pull quay.io/jasonish/suricata:8.0
docker pull ghcr.io/jasonish/suricata:7.0.15
```

--------------------------------

### Pass Suricata Options via Environment Variable

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Example of passing additional command-line options to Suricata using the SURICATA_OPTIONS environment variable. This allows for flexible configuration of Suricata's behavior.

```bash
docker run -e SURICATA_OPTIONS="-i eno1 -vvv" jasonish/suricata:latest
```

--------------------------------

### Run with Log Rotation Cron

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Example of running the Suricata container with the cron daemon enabled to handle scheduled tasks like log rotation. Requires the ENABLE_CRON environment variable to be set.

```bash
docker run --rm -it \
    -e ENABLE_CRON=yes \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Prepare to Build ARM Images on x86_64

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Set up QEMU user static binaries for multi-architecture builds on an x86_64 host. This is a prerequisite for building ARM images.

```bash
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
```

--------------------------------

### Example: PCAP File Analysis in Bridge Network Mode

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

This command runs Suricata in the default bridge mode to analyze a PCAP file, suitable for offline analysis without live network access.

```bash
docker run -it jasonish/suricata:latest -r /pcaps/traffic.pcap
```

--------------------------------

### Start Logstash Container with Volumes from Suricata

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Start a Logstash container that shares volumes with a running Suricata container to access logs.

```bash
docker run -it --net=host --volumes-from=suricata logstash /bin/bash
```

--------------------------------

### Recommended Capabilities for Live Capture

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

Includes net_admin, net_raw, and sys_nice capabilities along with host networking for live network traffic analysis.

```bash
docker run --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    --net=host jasonish/suricata:latest -i eth0
```

--------------------------------

### Build System Dependencies Overview

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/module-architecture.md

Lists the key files and commands used by the build script to construct the Docker image. This includes version files, CPU count, Docker commands, and configuration files.

```shell
build.sh
├─ $(cat VERSION)              # Read current version
├─ $(cat ../LATEST)            # Read latest version designation
├─ $(nproc --all)              # Query CPU count
└─ docker build                # Docker command
   ├─ Dockerfile.{arch}
   ├─ profiling.patch          # (7.0, 8.0 only)
   ├─ suricata-update.yaml
   ├─ suricata.logrotate
   └─ docker-entrypoint.sh

```

--------------------------------

### Initialize Suricata Configuration

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Copies default configuration files from /etc/suricata.dist to /etc/suricata if they do not already exist. This allows user customizations to persist.

```bash
for src in /etc/suricata.dist/*; do
    filename=$(basename ${src})
    dst="/etc/suricata/${filename}"
    if ! test -e "${dst}"; then
        echo "Creating ${dst}."
        cp -a "${src}" "${dst}"
    fi
done
```

--------------------------------

### Initialize Suricata Configuration

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Mount an empty directory to /etc/suricata to generate default configuration files. This is useful for creating a custom configuration.

```bash
mkdir ./etc
docker run --rm -it -v $(pwd)/etc:/etc/suricata jasonish/suricata:latest -V
```

--------------------------------

### Dockerfile Entrypoint Configuration

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Shows how the entrypoint script is configured in the Dockerfile. The script is copied to the root of the filesystem and set as the container's ENTRYPOINT.

```dockerfile
COPY /docker-entrypoint.sh /
ENTRYPOINT ["/docker-entrypoint.sh"]
```

--------------------------------

### Run Suricata with Podman and Capabilities

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Run the Suricata container using Podman, explicitly adding required capabilities.

```bash
sudo podman run --rm -it --net=host \
    --cap-add=net_admin,net_raw,sys_nice \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Create Suricata User and Set Permissions

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Creates a system user 'suricata', sets ownership for Suricata directories, copies default configuration, and restricts logrotate permissions.

```dockerfile
RUN useradd --system --create-home suricata && \
    chown -R suricata:suricata /etc/suricata && \
    chown -R suricata:suricata /var/log/suricata && \
    chown -R suricata:suricata /var/lib/suricata && \
    chown -R suricata:suricata /var/run/suricata && \
    cp -a /etc/suricata /etc/suricata.dist && \
    chmod 600 /etc/logrotate.d/suricata
```

--------------------------------

### Dump and Validate Configuration

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Run the container to parse the configuration file and print the resulting configuration as YAML, then exit. Useful for validating configuration syntax. Mount the configuration directory if needed.

```bash
docker run -v $(pwd)/etc:/etc/suricata jasonish/suricata:latest \
    --dump-config
```

--------------------------------

### Display Suricata Build Information

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Run the container to display detailed build information, including enabled features and library versions, then exit.

```bash
docker run jasonish/suricata:latest --build-info
```

--------------------------------

### List Supported Application Layer Protocols

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Run the container to list the application layer protocols supported by Suricata.

```bash
docker run jasonish/suricata:latest --list-app-layer-protocols
```

--------------------------------

### Get Suricata Runtime Statistics

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Prints current runtime statistics for Suricata, including packet counts and rule hits. The output is formatted as JSON.

```bash
docker exec -it suricata suricatasc -c stats
```

```bash
docker exec -it suricata suricatasc -c stats | jq .
```

--------------------------------

### Use Alternate Configuration File

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Run Suricata with a custom configuration file. Mount a local directory containing the custom configuration into the container. Useful for testing different settings.

```bash
docker run -v $(pwd)/custom:/custom jasonish/suricata:latest \
    -c /custom/custom-suricata.yaml -i eth0
```

--------------------------------

### Execute Suricata-Update in Running Container

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Execute Suricata-Update within a running Suricata container and then signal Suricata to reload its rules. Requires the Suricata container to be started with a name.

```bash
docker exec -it --user suricata suricata suricata-update -f
```

--------------------------------

### Bind Mount Configuration Directory

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

Mounts a local directory to the container's configuration path. The entrypoint copies default configurations if the volume is empty on first run.

```bash
mkdir -p ./etc
docker run -v $(pwd)/etc:/etc/suricata jasonish/suricata:latest
```

--------------------------------

### Assign a Fixed Name to the Container

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

The --name flag assigns a fixed name to the container, facilitating easy reference and volume sharing, especially in multi-container setups.

```bash
docker run --name=suricata jasonish/suricata:latest
```

--------------------------------

### Run Suricata with Host Network and Capabilities

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Run the Suricata container using the host network and necessary capabilities for network monitoring.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i <interface>
```

--------------------------------

### Pass Options via SURICATA_OPTIONS Environment Variable

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Use the SURICATA_OPTIONS environment variable to pass command-line options to Suricata. This example sets the network interface and verbosity level.

```bash
docker run --net=host -e SURICATA_OPTIONS="-i eno1 -vvv" jasonish/suricata:latest
```

--------------------------------

### Create Runtime Directories

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Creates essential directories for Suricata's runtime operation, including logs, sockets, and persistent data.

```dockerfile
RUN mkdir -p /var/log/suricata /var/run/suricata /var/lib/suricata
```

--------------------------------

### Pulling Version-Specific Suricata Images

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/image-tags-and-versioning.md

Examples of pulling exact Suricata version images. These tags are immutable and ensure you pull a specific release, automatically selecting the correct architecture.

```bash
docker pull jasonish/suricata:8.0.4
docker pull jasonish/suricata:7.0.15
docker pull jasonish/suricata:7.0.11
```

--------------------------------

### Handle Missing Capabilities

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/entrypoint.md

Checks for 'sys_nice' and 'net_admin' capabilities, printing warnings and disabling non-root execution if they are missing.

```bash
if ! check_for_cap sys_nice; then
    echo "Warning: no sys_nice capability, use --cap-add sys_nice"
    run_as_user="no"
fi
if ! check_for_cap net_admin; then
    echo "Warning: no net_admin capability, use --cap-add net_admin"
    run_as_user="no"
fi
```

--------------------------------

### Suricata + Logstash Multi-Container Setup

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Sets up Suricata and Logstash in separate containers, sharing the logs volume. This pattern allows Logstash to process Suricata's output logs.

```bash
# Start Suricata with named volumes
docker run -d --name=suricata --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
    jasonish/suricata:latest -i eth0

# Start Logstash sharing logs volume
docker run -d --name=logstash \
    --volumes-from=suricata \
    -v /etc/logstash/conf.d:/config \
    docker.elastic.co/logstash/logstash:latest \
    -f /config/suricata.conf

# Logs are visible to both containers
```

--------------------------------

### Run Suricata with Custom Configuration and Network

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Run Suricata with a custom configuration mounted from the host and with host networking enabled. Requires specific capabilities for network administration.

```bash
docker run --rm -it --net=host \
    -v $(pwd)/etc:/etc/suricata \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Configure Suricata Build Options

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Configures Suricata with various build-time options. Use custom CONFIGURE_ARGS for specific build variants.

```dockerfile
RUN ./configure \
        --prefix=/usr \
        --disable-shared \
        --disable-gccmarch-native \
        --enable-nfqueue \
        --enable-hiredis \
        --enable-geoip \
        --enable-ebpf \
        --enable-dpdk \
        --enable-profiling-rules \
        ${CONFIGURE_ARGS}
```

--------------------------------

### Bind Mount Logs Directory

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

Mounts a local directory to capture Suricata's log files, including eve.json, fast.log, and stats.log.

```bash
docker run -v $(pwd)/logs:/var/log/suricata jasonish/suricata:latest
```

--------------------------------

### Update Rules and Reload in Running Container

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Starts a Suricata container, then uses `docker exec` to update its rules and reload them. This is a common workflow for applying rule updates to a running Suricata instance.

```bash
# Start container
docker run -d --name=suricata --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i eth0

# Download and install rules
docker exec -it suricata suricata-update -f

# Reload rules in running Suricata
docker exec -it suricata suricatasc -c reload-rules
```

--------------------------------

### Create and Push Multi-Architecture Manifests

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Generates multi-architecture Docker image manifests for regular, profiling, major version, and potentially 'latest' or 'main' tags. It combines architecture-specific images into a single manifest for each tag.

```bash
if [[ "${MANIFEST}" = "yes" ]]; then
    for repo in "${REPOS[@]}"; do
        # Create manifests for regular variant
        docker manifest rm ${repo}:${VERSION} || true
        docker manifest create --amend \
               ${repo}:${VERSION} \
               ${repo}:${VERSION}-amd64 \
               ${repo}:${VERSION}-arm64
        docker manifest push ${repo}:${VERSION}
        
        # Create manifests for profiling variant
        docker manifest rm ${repo}:${VERSION}-profiling || true
        docker manifest create --amend \
               ${repo}:${VERSION}-profiling \
               ${repo}:${VERSION}-amd64-profiling \
               ${repo}:${VERSION}-arm64-profiling
        docker manifest push ${repo}:${VERSION}-profiling
        
        # Conditional: Create major version manifests
        docker manifest rm ${repo}:${MAJOR} || true
        docker manifest create --amend \
               ${repo}:${MAJOR} \
               ${repo}:${VERSION}-amd64 \
               ${repo}:${VERSION}-arm64
        docker manifest push ${repo}:${MAJOR}
        
        # ... similarly for profiling
        
        # Conditional: Create "latest" if MAJOR == LATEST
        if [[ "${MAJOR}" = "${LATEST}" ]]; then
            docker manifest rm ${repo}:latest || true
            docker manifest create --amend \
                   ${repo}:latest \
                   ${repo}:${VERSION}-amd64 \
                   ${repo}:${VERSION}-arm64
            docker manifest push ${repo}:latest
        fi
        
        # Conditional: Create "main"/"master" if MAJOR == "main"
        if [[ "${MAJOR}" = "main" ]]; then
            docker manifest rm ${repo}:main || true
            docker manifest create --amend \
                   ${repo}:main \
                   ${repo}:${VERSION}-amd64 \
                   ${repo}:${VERSION}-arm64
            docker manifest push ${repo}:main
            # (also creates master as alias)
        fi
    done
fi
```

--------------------------------

### Run Docker Suricata Container

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Basic syntax for running the jasonish/suricata container. Replace [tag] with the desired Suricata version tag.

```bash
docker run [docker-options] jasonish/suricata:[tag] [suricata-options]
```

--------------------------------

### Copy Configuration Files

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/dockerfile-reference.md

Copies custom configuration files into the Suricata runtime environment.

```dockerfile
COPY /update.yaml /etc/suricata/update.yaml
COPY /suricata.logrotate /etc/logrotate.d/suricata
```

--------------------------------

### Pulling the Latest Stable Suricata Image

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/image-tags-and-versioning.md

Examples of pulling the 'latest' tag, which points to the most recent stable release defined in the repository's LATEST file. This tag is recommended for stable production use.

```bash
docker pull jasonish/suricata:latest      # Currently pulls 8.0.x
docker pull quay.io/jasonish/suricata:latest
docker pull ghcr.io/jasonish/suricata:latest
```

--------------------------------

### Bind Mount Suricata Configuration Directory

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

This command demonstrates how to bind mount the host's local './etc' directory to the container's '/etc/suricata' path, allowing for persistent configuration management.

```bash
mkdir -p ./etc
docker run -it -v $(pwd)/etc:/etc/suricata jasonish/suricata:latest
```

--------------------------------

### Key Build Variables

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/module-architecture.md

Defines the repositories, architectures, and variants used in the build process. These variables control where images are pushed and what types of images are built.

```bash
REPOS=("docker.io/jasonish/suricata", "quay.io/jasonish/suricata", "ghcr.io/jasonish/suricata")
ARCHES=("amd64" "arm64")
VARIANTS=("regular" "profiling")
```

--------------------------------

### Systemd Service Unit for Suricata Container

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

A systemd service unit file to manage the Suricata Docker container as a background service on a host. It defines how to start and stop the container with specific network, capability, and volume configurations.

```ini
# /etc/systemd/system/suricata.service
[Unit]
Description=Suricata Docker Container
After=docker.service
Requires=docker.service

[Service]
Type=simple
Restart=always
ExecStart=/usr/bin/docker run --rm --name=suricata \
    --net=host \
    --cap-add=net_admin \
    --cap-add=net_raw \
    --cap-add=sys_nice \
    -v /var/log/suricata:/var/log/suricata \
    -v /etc/suricata:/etc/suricata \
    -v /var/lib/suricata:/var/lib/suricata \
    -e ENABLE_CRON=yes \
    jasonish/suricata:8.0 -i eth0

ExecStop=/usr/bin/docker stop suricata
ExecStopPost=/usr/bin/docker rm -f suricata

StandardOutput=journal
StandardError=journal
SyslogIdentifier=suricata

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

--------------------------------

### Build Loop for Architectures and Variants

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Iterates through defined repositories and architectures to build both regular and profiling variants of Docker images. Tags are formatted based on version, architecture, and variant.

```bash
if [[ "${BUILD}" = "yes" ]]; then
    for repo in "${REPOS[@]}"; do
        for arch in "${ARCHES[@]}"; do
            if [[ "${VARIANT}" = "regular" || "${VARIANT}" = "both" ]]; then
                tag=${repo}:${VERSION}-${arch}
                arch=${arch} tag=${tag} build
            fi

            if [[ "${VARIANT}" = "profiling" || "${VARIANT}" = "both" ]]; then
                tag=${repo}:${VERSION}-${arch}-profiling
                arch=${arch} tag=${tag} build \
                    "--enable-profiling --enable-profiling-locks"
            fi
        done
    done
fi
```

--------------------------------

### Directory Structure

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-internals.md

Overview of the Docker Suricata project's directory layout, highlighting key files and their purposes.

```text
docker-suricata/
├── LATEST                    # File: designates which major version is "latest"
├── README.md                 # Documentation
├── build.sh                  # Root build script (never run from root)
├── 7.0/
│   ├── VERSION               # File: "7.0.15"
│   ├── Dockerfile.amd64      # x86_64 build definition
│   ├── Dockerfile.arm64      # ARM64 build definition
│   ├── docker-entrypoint.sh  # Container initialization script
│   ├── profiling.patch       # Patch for profiling build variant
│   ├── suricata.logrotate    # Log rotation configuration
│   ├── update.yaml           # Suricata-update configuration
│   └── examples/
│       └── run.sh            # Example docker run command
├── 8.0/                      # Same structure as 7.0
├── main/                     # Same structure as 7.0
└── .git/
    └── ...

```

--------------------------------

### Build Arm64 Suricata Docker Image

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Build a Docker image for the arm64 architecture using the provided Dockerfile. Ensure you are in the correct version directory (e.g., '7.0').

```bash
cd 7.0
docker build --build-arg=$(cat VERSION) -f Dockerfile.arm64 .
```

--------------------------------

### Use Sudo on Host for Permissions

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Demonstrates using sudo on the host to edit Suricata configuration files and change ownership of mounted directories. This is an alternative to setting PUID/PGID within the container.

```bash
sudo vim ./etc/suricata.yaml
sudo chown -R $USER:$USER ./etc ./logs ./data
```

--------------------------------

### List Available Suricata Rule Sources

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Lists all available rule sources that can be enabled for Suricata-Update. The output includes the source name, version, license, and description.

```bash
docker exec -it suricata suricata-update list-sources
```

--------------------------------

### Build x86_64 Suricata Docker Image

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Build a Docker image for the amd64 architecture using the provided Dockerfile. Ensure you are in the correct version directory (e.g., '7.0').

```bash
cd 7.0
docker build --build-arg=$(cat VERSION) -f Dockerfile.amd64 .
```

--------------------------------

### Pulling Development/Testing Versions

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/image-tags-and-versioning.md

Use the 'main' tag for the latest features and fixes. This tag is recommended for development and testing but carries a risk of instability and potential breaking changes, as it may change daily.

```bash
docker pull jasonish/suricata:main

```

--------------------------------

### Run Suricata with Host Network, Capabilities, and Log Volume

Source: https://github.com/jasonish/docker-suricata/blob/main/README.md

Run Suricata, mapping the host's logs directory to the container's log directory for persistent log access.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
	jasonish/suricata:latest -i <interface>
```

--------------------------------

### Download and Compile Suricata Rules

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Downloads rules from enabled sources, merges them, and compiles them into Suricata format. Options allow forcing downloads, skipping tests, or preventing automatic reloads.

```bash
docker exec -it suricata suricata-update -f
```

```bash
docker exec -it suricata suricata-update -f --no-reload
```

--------------------------------

### Recommended Capability Set for Non-Root Operation

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

This command bundles the essential capabilities (net_admin, net_raw, sys_nice) for running Suricata in a non-root user mode, ideal for live packet capture.

```bash
docker run --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Build Repositories Configuration

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/build-system.md

An array defining the target registries for pushing Docker images. The script pushes to these repositories.

```bash
REPOS=(
    "docker.io/jasonish/suricata"
    "quay.io/jasonish/suricata"
    "ghcr.io/jasonish/suricata"
)
```

--------------------------------

### Suricata with Cron and Logrotate Enabled

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/container-configuration.md

Enables cron and logrotate services within the container using the ENABLE_CRON environment variable for automated tasks. Requires host networking and specific capabilities.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
    -e ENABLE_CRON=yes \
    jasonish/suricata:latest -i eth0
```

--------------------------------

### Build and Push Docker Image

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/INDEX.md

Builds the Docker image for Suricata and pushes it to all configured registries. Ensure you are in the correct version directory (e.g., '8.0').

```bash
cd 8.0
./build.sh --push --manifest
```

--------------------------------

### List Suricata Rule Keywords

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Run the container to list all available rule keywords. This is useful for rule writing reference.

```bash
docker run jasonish/suricata:latest --list-keywords
```

--------------------------------

### Set PUID and PGID for Permissions

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Configures the Suricata container to run with the host user's UID and GID, resolving permission issues with bind-mounted directories. This allows the host user to edit files without sudo.

```bash
docker run -e PUID=$(id -u) -e PGID=$(id -g) \
    -v $(pwd)/etc:/etc/suricata \
    jasonish/suricata:latest
```

--------------------------------

### Pull and Run Profiling Variant

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/image-tags-and-versioning.md

Demonstrates how to pull and run a specific profiling variant of the Suricata Docker image. Use profiling variants for performance analysis.

```bash
docker pull jasonish/suricata:8.0-profiling
docker run jasonish/suricata:8.0-profiling -i eth0
```

--------------------------------

### Monitor Live Interface with Suricata

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Runs Suricata in a Docker container to monitor a live network interface (`eth0`). It mounts a local directory for logs and sets verbose output.

```bash
docker run --rm -it --net=host \
    --cap-add=net_admin --cap-add=net_raw --cap-add=sys_nice \
    -v $(pwd)/logs:/var/log/suricata \
    -e SURICATA_OPTIONS="-i eth0 -vv" \
    jasonish/suricata:latest
```

--------------------------------

### Display Suricata Version

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/command-reference.md

Run the container to display the Suricata version information and exit.

```bash
docker run jasonish/suricata:latest -V
```

--------------------------------

### Kubernetes Deployment Command

Source: https://github.com/jasonish/docker-suricata/blob/main/_autodocs/network-and-deployment.md

Command to apply the Suricata DaemonSet configuration to a Kubernetes cluster.

```bash
kubectl apply -f suricata-daemonset.yaml
```