Security Best Practices

Overview

Esprit is a powerful security testing tool that executes potentially dangerous operations. Follow these best practices to ensure secure deployment and operation.

Isolation and Sandboxing

Docker Container Isolation

Esprit runs all security scans inside isolated Docker containers to prevent damage to the host system. Default isolation features:

Non-root user execution (pentester user)
Limited filesystem access (/workspace working directory)
Network namespace isolation
Resource limits (configurable)

Container configuration (from esprit/runtime/docker_runtime.py:161-180):

container = self.client.containers.run(
    image_name,
    cap_add=["NET_ADMIN", "NET_RAW"],  # Required for network scanning
    hostname=container_name,
    tty=True,
    detach=True,
)

Network Capabilities

The sandbox requires elevated network capabilities for security testing:

cap_add:
  - NET_ADMIN  # Network administration (routing, interfaces)
  - NET_RAW    # Raw socket access (for nmap, tcpdump)

Risk mitigation:

Capabilities are scoped to the container only
No access to host network interfaces
Automatic cleanup on scan completion

Resource Limits

Set Docker resource limits to prevent resource exhaustion:

# In docker run configuration
docker run \
  --memory="4g" \
  --memory-swap="4g" \
  --cpus="2.0" \
  --pids-limit 200 \
  esprit-sandbox

For Esprit runtime, configure via environment:

export ESPRIT_SANDBOX_TIMEOUT=60
export ESPRIT_SANDBOX_EXECUTION_TIMEOUT=120

Authentication and Secrets Management

LLM API Keys

Never commit API keys to version control:

# Bad
export LLM_API_KEY="sk-ant-123456789..."

# Good - use environment variables
export LLM_API_KEY="$(cat /secure/path/to/key)"

# Better - use secrets management
export LLM_API_KEY="$(vault read -field=key secret/esprit/llm)"

Esprit Cloud Authentication

Esprit Cloud uses OAuth tokens with automatic refresh:

# Login (opens browser for OAuth)
esprit provider login esprit

# Token stored securely in ~/.esprit/credentials.json
# Permissions: 0600 (user read/write only)

Token storage (from esprit/config/config.py:92-99):

@classmethod
def config_file(cls) -> Path:
    return cls.config_dir() / "cli-config.json"

# Secured with 0600 permissions (line 123)
config_path.chmod(0o600)

CI/CD Secrets

Store sensitive credentials in CI/CD secrets, never in code: GitHub Actions:

env:
  ESPRIT_TOKEN: ${{ secrets.ESPRIT_TOKEN }}
  LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

GitLab CI:

variables:
  ESPRIT_TOKEN: ${ESPRIT_TOKEN}  # Defined in CI/CD settings

Network Security

Proxy Configuration

The sandbox runs Caido proxy for HTTP/HTTPS interception (from containers/docker-entrypoint.sh:12-46):

caido-cli --listen 127.0.0.1:${CAIDO_PORT} \
          --allow-guests \
          --no-logging \
          --import-ca-cert /app/certs/ca.p12

Security considerations:

Proxy listens on 127.0.0.1 only (not exposed to host)
Auto-generated CA certificate per container
Automatic cleanup on container destruction

TLS/SSL Certificate Handling

Sandbox CA generation (from containers/Dockerfile:52-67):

RUN openssl ecparam -name prime256v1 -genkey -noout -out /app/certs/ca.key && \
    openssl req -x509 -new -key /app/certs/ca.key \
    -out /app/certs/ca.crt \
    -days 3650 \
    -subj "/C=US/ST=CA/O=Security Testing/CN=Testing Root CA"

Trust store updates:

# CA added to system trust store
cp /app/certs/ca.crt /usr/local/share/ca-certificates/
update-ca-certificates

Firewall Rules

Isolate scan containers from internal networks:

# iptables example
iptables -A DOCKER-USER -s 172.17.0.0/16 -d 10.0.0.0/8 -j DROP
iptables -A DOCKER-USER -s 172.17.0.0/16 -d 192.168.0.0/16 -j DROP

Or use Docker network policies:

docker network create --internal esprit-isolated

Data Protection

Scan Results Storage

Scan results are stored locally by default:

~/.esprit/scans/<scan-id>/
  ├── report.json
  ├── findings/
  └── logs/

Permissions:

Results directory: 0700 (user only)
Report files: 0600 (user read/write only)

Encryption at rest:

# Use encrypted filesystem for sensitive scans
mkdir /encrypted/esprit-scans
mount -t ecryptfs /encrypted/esprit-scans ~/.esprit/scans

Sensitive Data Exclusion

Exclude sensitive directories from scans (from esprit/runtime/docker_runtime.py:246-266):

EXCLUDE_DIRS = {
    "node_modules",
    ".git",
    ".env",          # Environment files
    "env",
    ".venv",
    "venv",
    ".coverage",
    "dist",
    "build",
}

Never commit sensitive files:

# .gitignore
.env
.env.*
credentials.json
*.key
*.pem
secrets/

Log Sanitization

Esprit automatically sanitizes sensitive data from logs:

# API keys masked in logs
LOG: Using LLM: anthropic/claude-sonnet-4-5
LOG: API Key: sk-ant-***...***

Cloud Runtime Security

Esprit Cloud Isolation

Esprit Cloud sandboxes run in isolated environments:

Dedicated container per scan
Automatic cleanup after scan completion
Network isolation from other tenants
Encrypted communication (TLS 1.3)

State tracking (from esprit/runtime/cloud_runtime.py:85-95):

@classmethod
def _save_tracked_sandboxes(cls, entries: list[dict[str, str]]) -> None:
    path = cls._state_file_path()
    payload = {"version": 1, "sandboxes": entries}
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp_path = path.with_suffix(path.suffix + ".tmp")
    tmp_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
    tmp_path.replace(path)

Cleanup on Termination

Esprit Cloud automatically cleans up stale sandboxes:

async def cleanup_stale_sandboxes(cls, access_token: str, api_base: str) -> int:
    """Best-effort cleanup for sandboxes left by abrupt process termination."""
    tracked = cls._load_tracked_sandboxes()
    for item in tracked:
        response = await client.delete(
            f"{api_base}/sandbox/{sandbox_id}",
            headers={"Authorization": f"Bearer {access_token}"},
        )

Vulnerability Disclosure

Responsible Disclosure

Esprit is designed for authorized security testing only:

Written Permission - Always obtain explicit written authorization
Scope Definition - Define clear testing boundaries
Legal Compliance - Comply with local laws and regulations
Responsible Disclosure - Follow responsible vulnerability disclosure practices

Automated Scanning Disclaimer

Include disclaimers in scan reports:

esprit scan https://example.com \
  --instruction "Include legal disclaimer: This scan was performed under authorization from [Company] on [Date]. Report ID: [Unique ID]"

Operational Security

Rate Limiting

Implement rate limiting for API-based scans:

# Environment configuration
export ESPRIT_LLM_MAX_RETRIES=5
export LLM_TIMEOUT=300

Telemetry and Monitoring

Esprit includes telemetry for usage tracking (from pyproject.toml:48):

esprit_telemetry = "1"  # Default enabled

Disable telemetry:

export ESPRIT_TELEMETRY=0

What’s collected:

Anonymized usage statistics
Error reports (no sensitive data)
Performance metrics

Not collected:

Scan targets or URLs
API keys or credentials
Vulnerability details
Source code or file contents

Audit Logging

Enable comprehensive logging for compliance:

# Set logging level
export ESPRIT_LOG_LEVEL=INFO

# Log to file
export ESPRIT_LOG_FILE=~/.esprit/logs/audit.log

Container Security

Image Verification

Verify Docker image signatures before use:

# Enable Docker Content Trust
export DOCKER_CONTENT_TRUST=1

# Pull verified image
docker pull improdead/esprit-sandbox:latest

Base Image Security

The Esprit sandbox is based on Kali Linux with security updates:

RUN apt-get update && \
    apt-get install -y kali-archive-keyring sudo && \
    apt-get update && \
    apt-get upgrade -y

Update frequency:

Base image rebuilt weekly
Security patches applied immediately
Dependency updates via Dependabot

Vulnerability Scanning

Scan custom images for vulnerabilities:

# Using Trivy
trivy image yourorg/esprit-custom:latest

# Using Clair
clair-scanner yourorg/esprit-custom:latest

Access Control

File System Permissions

Esprit configuration directory:

ls -la ~/.esprit/
drwx------  .esprit/              # 0700
-rw-------  cli-config.json       # 0600
-rw-------  credentials.json      # 0600
drwx------  scans/                # 0700

Multi-User Environments

In shared environments, use user-scoped installations:

# Install per-user
export ESPRIT_HOME="$HOME/.local/esprit"
curl -fsSL https://raw.githubusercontent.com/esprit-cli/Esprit/main/scripts/install.sh | bash

Role-Based Access Control

For team environments, implement RBAC:

# Example: Limit scan targets
apiVersion: rbac/v1
kind: Role
metadata:
  name: esprit-scanner
rules:
  - targets:
      - "https://staging.example.com"
      - "https://test.example.com"
    permissions:
      - scan
      - read

Compliance and Certifications

Data Residency

Esprit Cloud supports data residency requirements:

# Specify region (if supported)
export ESPRIT_CLOUD_REGION=us-east-1

Compliance Standards

SOC 2 Type II - Annual audits for Esprit Cloud
GDPR - EU data protection compliance
ISO 27001 - Information security management

Audit Reports

Request compliance reports:

esprit report --format compliance --standard soc2

Incident Response

Security Incident Reporting

Report security issues to: [email protected] Include:

Detailed description
Steps to reproduce
Potential impact
Suggested mitigation

Emergency Procedures

If you suspect a breach:

Immediately stop all scans: docker stop $(docker ps -q --filter label=esprit-scan-id)
Rotate credentials: Update all API keys and tokens
Review logs: Check ~/.esprit/logs/ for suspicious activity
Contact support: Email [email protected] with incident details

Hardening Checklist

Security Tools Included

The Esprit sandbox includes security-hardened tools (from containers/Dockerfile:25-46):

Static Analysis: Semgrep, Bandit, TruffleHog, Trivy
Network Scanning: nmap, masscan, naabu
Web Testing: Nuclei, FFUF, SQLMap, Wapiti
API Testing: httpx, katana
Code Analysis: ESLint, JSHint, Retire.js

All tools are:

Installed from official sources
Verified with checksums where available
Updated regularly
Configured with security best practices

Best Practices Summary

Isolation - Always run scans in isolated Docker containers
Authentication - Use OAuth and secrets management for credentials
Authorization - Obtain written permission before testing
Encryption - Use TLS for all network communication
Least Privilege - Run with minimum required permissions
Monitoring - Enable audit logging and telemetry
Updates - Keep Esprit and dependencies current
Compliance - Follow industry standards and regulations
Incident Response - Have a plan for security incidents
Documentation - Document all customizations and configurations

Development

Deployment

​Overview

​Isolation and Sandboxing

​Docker Container Isolation

​Network Capabilities

​Resource Limits

​Authentication and Secrets Management

​LLM API Keys

​Esprit Cloud Authentication

​CI/CD Secrets

​Network Security

​Proxy Configuration

​TLS/SSL Certificate Handling

​Firewall Rules

​Data Protection

​Scan Results Storage

​Sensitive Data Exclusion

​Log Sanitization

​Cloud Runtime Security

​Esprit Cloud Isolation

​Cleanup on Termination

​Vulnerability Disclosure

​Responsible Disclosure

​Automated Scanning Disclaimer

​Operational Security

​Rate Limiting

​Telemetry and Monitoring

​Audit Logging

​Container Security

​Image Verification

​Base Image Security

​Vulnerability Scanning

​Access Control

​File System Permissions

​Multi-User Environments

​Role-Based Access Control

​Compliance and Certifications

​Data Residency

​Compliance Standards

​Audit Reports

​Incident Response

​Security Incident Reporting

​Emergency Procedures

​Hardening Checklist

​Security Tools Included

​Best Practices Summary

​See Also

Build docs developers (and LLMs) love