Tamandua ML Service

AI security scanning and machine learning service for the Tamandua EDR platform.

tamandua-scan CLI

A standalone command-line tool for scanning AI model files for security threats.

Installation

Option 1: Download pre-built binary (recommended)

Download from GitHub Releases:

• tamandua-scan-linux-x64 - Linux x64
• tamandua-scan-windows-x64.exe - Windows x64
• tamandua-scan-macos-x64 - macOS x64

# Linux/macOS
chmod +x tamandua-scan-linux-x64
./tamandua-scan-linux-x64 --help

# Windows
tamandua-scan-windows-x64.exe --help

Option 2: Install via pip

pip install tamandua-scan
tamandua-scan --help

Option 3: Install from source

cd apps/tamandua_ml
pip install -e ".[cli]"
tamandua-scan --help

Usage

# Scan a single file
tamandua-scan model.pkl

# Scan a directory recursively
tamandua-scan ./models/

# Output as text table
tamandua-scan ./models/ --format text

# Output as SARIF for CI/CD
tamandua-scan ./models/ --format sarif --output results.sarif

# Filter by severity
tamandua-scan . --severity high

# Watch mode (continuous scanning)
tamandua-scan ./models/ --watch

Supported Formats

Extension	Format	Threats Detected
.pkl, .pickle, .pt, .pth	Pickle	Code execution via dangerous imports
.gguf	GGUF	Template injection (CVE-2024-34359)
.safetensors	Safetensors	Metadata anomalies
.onnx	ONNX	External file references, custom ops

Exit Codes

Code	Meaning
0	All files clean
1	Threats detected
2	Error occurred

CI/CD Integration

GitHub Actions example:

- name: Scan AI models
  run: |
    wget https://github.com/treant-lab/tamandua-ml/releases/latest/download/tamandua-scan-linux-x64
    chmod +x tamandua-scan-linux-x64
    ./tamandua-scan-linux-x64 ./models/ --format sarif --output results.sarif

- name: Upload SARIF to GitHub Security
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Building from Source

# Linux/macOS
./scripts/build.sh

# Windows
.\scripts\build.ps1

Binary will be in dist/tamandua-scan (or dist/tamandua-scan.exe on Windows).

---

ML Service API

The Tamandua ML service provides REST endpoints for model inference and threat detection.

For the governed malware-detection training roadmap, dataset acquisition gates, vx-underground/InTheWild handling, ONNX export/parity, and benchmark execution order, see ../../docs/benchmarks/ML_TRAINING_PIPELINE_ROADMAP.md.

Running the Service

# Using Docker
docker-compose up tamandua-ml

# From source
cd apps/tamandua_ml
pip install -e .
uvicorn api.main:app --host 0.0.0.0 --port 8000

API Endpoints

• POST /api/v1/scan/pickle - Scan a pickle file for security threats
• POST /api/v1/scan/gguf - Scan a GGUF file for template injection
• POST /api/v1/scan/safetensors - Validate safetensors metadata
• POST /api/v1/scan/onnx - Scan an ONNX model for security issues
• GET /health - Health check endpoint

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Lint
ruff check .
black --check .

# Format
ruff check --fix .
black .

License

Apache-2.0