Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/garagon/aguara/llms.txt

Use this file to discover all available pages before exploring further.

Aguara provides an official Docker image for running security scans in containerized environments without installing binaries on the host system.

​
Quick Start

# Scan current directory
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan

# Scan with options
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --severity high --format json
The image is hosted at ghcr.io/garagon/aguara and updated with every release.

​
Image tags

TagDescription
latestLatest stable release
v0.5.0Specific version (recommended for CI)
mainLatest commit from main branch (unstable)
# Use latest
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara:latest scan /scan

# Pin to version
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara:v0.5.0 scan /scan

​
Dockerfile

The official Aguara image is built from this Dockerfile: 
FROM golang:1.25-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags "-s -w" -o /aguara ./cmd/aguara

FROM alpine:3.21
RUN apk add --no-cache git
COPY --from=builder /aguara /usr/local/bin/aguara
ENTRYPOINT ["aguara"]
CMD ["scan", "."]
The image includes git to support --changed mode for incremental scanning.

​
Usage patterns

​
Mount current directory

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan
Mounts your current directory as /scan inside the container and scans it.

​
Scan specific subdirectory

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan/.claude/skills/

​
Output to file

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --format json -o /scan/results.json
Outputs to results.json in your current directory (accessible via the volume mount).

​
Fail on severity threshold

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --fail-on high
if [ $? -ne 0 ]; then
  echo "High or critical findings detected"
  exit 1
fi

​
CI mode

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --ci
Equivalent to --fail-on high --no-color.

​
Custom rules directory

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --rules /scan/custom-rules/
Mounts your directory and loads custom rules from ./custom-rules/.

​
Multiple volumes

docker run --rm \
  -v "$(pwd)/skills":/skills:ro \
  -v "$(pwd)/custom-rules":/rules:ro \
  -v "$(pwd)/output":/output \
  ghcr.io/garagon/aguara scan /skills --rules /rules -o /output/results.sarif
Mounts skills (read-only), custom rules (read-only), and output directory (read-write).

​
CI/CD integration

​
GitHub Actions

steps:
  - uses: actions/checkout@v4
  
  - name: Scan with Docker
    run: |
      docker run --rm -v "${{ github.workspace }}":/scan \
        ghcr.io/garagon/aguara:v0.5.0 scan /scan --ci
No installation step required — the action pulls the image and runs the scan.

​
GitLab CI

aguara-scan:
  stage: test
  image: ghcr.io/garagon/aguara:v0.5.0
  script:
    - aguara scan /builds/$CI_PROJECT_PATH --format sarif -o gl-sast-report.sarif --fail-on high
  artifacts:
    reports:
      sast: gl-sast-report.sarif
    when: always
Use the Aguara image directly as the job image — no docker-in-docker required.

​
CircleCI

jobs:
  security-scan:
    docker:
      - image: ghcr.io/garagon/aguara:v0.5.0
    steps:
      - checkout
      - run:
          name: Scan for security issues
          command: aguara scan . --ci

​
Jenkins

pipeline {
  agent any
  stages {
    stage('Security Scan') {
      steps {
        script {
          docker.image('ghcr.io/garagon/aguara:v0.5.0').inside {
            sh 'aguara scan /workspace --format sarif -o aguara-results.sarif --fail-on high'
          }
        }
      }
    }
  }
  post {
    always {
      archiveArtifacts artifacts: 'aguara-results.sarif', allowEmptyArchive: true
    }
  }
}

​
Bitbucket Pipelines

pipelines:
  default:
    - step:
        name: Aguara Security Scan
        image: ghcr.io/garagon/aguara:v0.5.0
        script:
          - aguara scan . --ci
        artifacts:
          - aguara-results.sarif

​
Advanced usage

​
Incremental scanning with git

# Mount .git to enable --changed mode
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --changed
The image includes git, so --changed detects modified files from the mounted .git directory.

​
Rug-pull detection with state persistence

# Create state directory
mkdir -p ~/.aguara

# Mount state directory
docker run --rm \
  -v "$(pwd)":/scan \
  -v "$HOME/.aguara":/root/.aguara \
  ghcr.io/garagon/aguara scan /scan --monitor
Persists scan state across runs to detect file changes (rug-pull attacks).

​
Override entrypoint

# Run a shell
docker run --rm -it --entrypoint /bin/sh ghcr.io/garagon/aguara

# Run a different command
docker run --rm ghcr.io/garagon/aguara list-rules --format json

​
Build custom image with embedded rules

FROM ghcr.io/garagon/aguara:v0.5.0
COPY custom-rules/ /custom-rules/
ENTRYPOINT ["aguara", "scan", ".", "--rules", "/custom-rules/"]
Build and run: 
docker build -t myorg/aguara-custom .
docker run --rm -v "$(pwd)":/scan myorg/aguara-custom /scan

​
Multi-platform builds

The official image supports linux/amd64 and linux/arm64: 
# Pull and run on ARM (e.g. M1/M2 Mac)
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara:latest scan /scan

# Build your own multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 -t myorg/aguara:latest .

​
Output formats in Docker

​
Terminal (default)

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --format terminal
Use --no-color if your terminal doesn’t support ANSI: 
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --no-color

​
JSON

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --format json -o /scan/results.json

​
SARIF

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --format sarif -o /scan/results.sarif

​
Markdown

docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --format markdown -o /scan/report.md

​
Troubleshooting

​
Permission denied errors

Output files are created as root inside the container. Fix ownership: 
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan -o /scan/results.json
sudo chown $USER:$USER results.json
Or run with the current user: 
docker run --rm --user $(id -u):$(id -g) -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan

​
.git directory not detected

Ensure .git is inside the mounted directory: 
# Wrong: only mounts ./skills/, not .git
docker run --rm -v "$(pwd)/skills":/scan ghcr.io/garagon/aguara scan /scan --changed

# Correct: mounts entire repo including .git
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan/skills --changed

​
Image pull rate limit

GitHub Container Registry (ghcr.io) has rate limits for unauthenticated pulls. Authenticate: 
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
docker pull ghcr.io/garagon/aguara:latest

​
Large scan times out

Increase Docker’s resource limits or use --changed mode: 
docker run --rm --memory=4g --cpus=4 -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan
Or scan incrementally: 
docker run --rm -v "$(pwd)":/scan ghcr.io/garagon/aguara scan /scan --changed

​
Docker Compose

services:
  aguara:
    image: ghcr.io/garagon/aguara:v0.5.0
    volumes:
      - ./:/scan:ro
      - ./output:/output
    command: scan /scan --format sarif -o /output/results.sarif --fail-on high
Run: 
docker-compose run --rm aguara

​
Next Steps

GitHub Actions

Integrate with GitHub Actions workflows

GitLab CI

Integrate with GitLab CI/CD pipelines

Build docs developers (and LLMs) love

Get started for freeTalk to us