Docker (Quick Start)

The fastest way to run Vault1337. Uses SQLite — data is not persisted after the container stops.

docker pull vault1337/vault1337:latest

docker run -p 8000:8000 \
  -e SECRET_KEY=change-me-to-a-long-random-string \
  -e DEBUG=True \
  vault1337/vault1337:latest

Username: admin
Password: changeme123

Docker Compose

Recommended for persistent deployments. Spins up Vault1337 with a PostgreSQL database and named volumes for samples and YARA rules.

git clone https://github.com/DanDreadless/Vault1337.git
cd Vault1337/Docker

docker compose up -d

# View logs
docker compose logs -f

# Stop the stack (data preserved)
docker compose down

# Stop and wipe all data
docker compose down -v

Local Development

Requires Python 3.12+, Node.js 22+, and (optionally) PostgreSQL.

git clone https://github.com/DanDreadless/Vault1337.git
cd Vault1337
python3 -m venv env
source env/bin/activate   # Windows: env\Scripts\activate
pip install -r requirements.txt

# Ubuntu / Debian
sudo apt install -y libimage-exiftool-perl libmpc-dev libgl1 libglib2.0-0

cp Docker/.env .env
# Edit .env — set SECRET_KEY and DEBUG=True
# Leave DATABASE_URL empty to use SQLite

python manage.py migrate
python manage.py createsuperuser

python manage.py runserver

cd frontend
npm install
npm run dev

Environment Variables

All configuration is handled via environment variables loaded from a .env file (or passed directly to the container).

API Keys

Third-party intelligence features require API keys. Add them via the web UI at Admin → API Keys (staff account required), or set them in your .env file before starting the container.

Uploading Samples

Navigate to Upload in the navigation bar. Four ingestion methods are available:

All samples are stored by SHA256 hash. Original filenames are preserved in the database but never used as file paths on disk. Add comma-separated tags during upload for easier organisation.

Analysis Tools

Open a sample from the vault and select a tool from the Analysis tab. Results are displayed inline and cached for the session.

YARA Rules

Navigate to YARA in the navigation bar to manage rules.

• Create new rules using the built-in editor — paste or write YARA syntax directly.
• Edit existing rules at any time.
• Run all rules against a specific sample from the sample detail page using the YARA tool.
• Rules are stored as .yar files in vault/yara-rules/ on the server.

IOC Management

Navigate to IOCs to view all extracted indicators of compromise across all samples.

• Run the IOC Extractor tool on a sample to populate its IOCs.
• Each IOC is linked back to the sample it came from.
• Mark IOCs as true positive or false positive using the toggle on the IOC page.
• Filter the list by classification (true / false / unreviewed) and search by value.

IP Intelligence

Navigate to IP Check to query an IP address against multiple threat intelligence sources simultaneously.

• Aggregates results from AbuseIPDB, Spur, and Shodan in a single request.
• Private, loopback, and reserved IP ranges are rejected before any external query is made.
• Requires at least one API key to be configured for results to be returned.

Tags & Search

• Add comma-separated tags when uploading a sample.
• Add or remove tags from any sample on the sample detail page.
• All tags are stored in lowercase automatically.
• Use the search bar on the Vault page to filter samples by filename, hash, or tag.
• Results are paginated — use the page controls at the bottom of the vault list.

Tech Stack

REST API

All endpoints are under /api/v1/. JWT Bearer token authentication is required on all endpoints except registration and token endpoints.

Interactive API documentation (Swagger UI) is available at /api/v1/docs/ on any running instance.