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

Docker Development

Use the localdev overlay to run the Django + React stack in Docker while keeping your local db.sqlite3 and sample_storage/ mounted directly from the host. Ideal for day-to-day development without a full PostgreSQL setup.

chmod 666 db.sqlite3
chmod -R 777 sample_storage/

docker compose \
  -f Docker/docker-compose.yml \
  -f Docker/docker-compose.build.yml \
  -f Docker/docker-compose.localdev.yml \
  up --build

# Rebuild after backend dependency changes
docker compose -f Docker/docker-compose.yml \
  -f Docker/docker-compose.build.yml \
  -f Docker/docker-compose.localdev.yml \
  up --build

# Stop without removing volumes
docker compose -f Docker/docker-compose.yml \
  -f Docker/docker-compose.localdev.yml \
  down

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

SECRET_KEY=change-me-to-a-long-random-string
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost
# Leave DATABASE_URL unset 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 Management → 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.

Vault Page

The Vault page lists all stored samples with filtering, search, and bulk management controls.

File Type Filter Chips

A row of filter chips above the sample table lets you quickly narrow the list to a specific file category:

Bulk Delete

Each row has a checkbox. Tick one or more rows (or use the header checkbox to select all on the current page) and a Delete N selected button appears in the page header. Clicking it prompts for confirmation then deletes all selected samples in parallel. The selection is cleared and the table reloads after deletion.

Pagination

The bottom of the vault list shows « ‹ page X of Y › » controls — first, previous, next, and last page buttons alongside the current page indicator.

Analysis Tools

Open a sample from the vault and select the Tools tab. The tool selector automatically filters and groups available tools based on the detected file type (PE, ELF, Mach-O, document, archive, email, script). A Show all tools checkbox is available for edge cases such as polyglot files.

Universal — all file types

Windows (PE)

Linux (ELF)

macOS (Mach-O)

Documents & PDFs

Archives & Email

Images

Android (APK)

Scripts & .NET

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 Run YARA Rules tool.
• Results show the matching rule name, tags, matched string identifiers, file offsets, and match lengths.
• 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 Extract IOCs 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 by IOC type using the filter chips above the table.
• Search by IOC value using the search box.

Auto-Enrichment

When the Extract IOCs tool runs, newly extracted ip and domain IOCs are automatically enriched against threat intel APIs in a background thread — the tool response returns immediately while enrichment continues asynchronously.

• IP IOCs — queried against VirusTotal and AbuseIPDB concurrently.
• Domain IOCs — queried against VirusTotal.
• An IOC is marked true positive if the VT malicious count meets the threshold or the AbuseIPDB score meets the threshold. It is marked false positive if all sources return clean results.
• RFC1918 private IPs (10/8, 172.16/12, 192.168/16) are saved as IOCs (useful for lateral movement analysis) but auto-marked false positive — they are never sent to external APIs.
• Loopback, link-local, multicast, and other reserved IP ranges are discarded entirely at extraction time.

The enrichment column in the IOC table shows results as VT: x/y (malicious/total engines) and AIPDB: z% (abuse score). A dash (—) is shown for IOC types not yet enriched or where no API key is configured.

Bulk Actions

Each row in the IOC table has a checkbox. Selecting one or more rows reveals a bulk action bar with two options:

• Export STIX — exports the selected IOCs as a STIX 2.1 bundle (see STIX 2.1 Export below).
• Delete — permanently removes the selected IOCs. Requires a confirmation click to prevent accidental deletion (staff only).

Manual Override & Re-Enrichment

• Manually toggling an IOC's true/false status sets an overridden flag, shown as a grey pill next to the status badge. Subsequent background enrichment runs will not overwrite a manually overridden IOC.
• A Re-enrich button is available on each ip and domain row. Clicking it triggers a synchronous re-enrichment (both VT and AbuseIPDB in parallel) and immediately refreshes the row. This clears the overridden flag so fresh data is applied.

Enrichment Thresholds (Environment Variables)

IOC types extracted:

IP & Domain Intelligence

IP Check

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

• Displays a colour-coded verdict banner (Malicious / Suspicious / Clean / Unknown) derived from all sources combined.
• Individual source cards: VirusTotal (detection count + link), AbuseIPDB (score bar + usage type + ISP), Spur (tunnel/tag badges), Shodan (open ports, hostnames, CVEs).
• Source cards with missing API keys are sorted to the bottom of the page.
• Private, loopback, and reserved IP ranges are rejected before any external query is made.

Domain Check

Navigate to Domain Check to query a domain against VirusTotal and WHOIS.

• Displays a verdict banner derived from VirusTotal detections.
• Individual source cards: VirusTotal (detection count, category badges + link), WHOIS (registrar, creation/expiry dates, name servers, status badges), Passive DNS (unique IPs seen resolving to this domain).
• Cards with missing API keys are sorted to the bottom.

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.

Analyst Notes

Analyst notes let you attach structured commentary to any sample — useful for documenting findings, sharing context with team members, and capturing initial triage decisions.

• Open a sample and select the Notes tab on the sample detail page.
• Each note has a title, a body (supports Markdown formatting), and a type label.
• Note types include: note (general observation), triage (initial assessment), ioc (indicator context), and malware (malware family / campaign attribution).
• Notes are preserved across sessions and visible to all users with access to the sample.
• Notes appear in the PDF report export under the Analyst Notes section.

Sample Report

Every sample has a structured JSON report available at GET /api/v1/files/{id}/report/. The report aggregates all stored analysis data in a single response — no new analysis is run.

The report includes:

• File metadata — name, size, magic bytes, MIME type, upload date, uploader
• Hashes — MD5, SHA1, SHA256, SHA512
• Tags — all tags applied to the sample
• VirusTotal summary — detection counts (malicious / suspicious / undetected / harmless), threat label, threat category, scan date, and known names
• IOCs — all confirmed (true positive) IOCs grouped by type

PDF Report Export

Every sample detail page has a PDF Report button on the Info tab. Clicking it generates a professional A4 PDF report entirely in-browser — no server round-trip is required beyond the initial page load.

The PDF is built from data already loaded on the page and downloads instantly with the filename:

vault1337_report_<sha256[:12]>_<YYYYMMDD>.pdf

Report sections:

MITRE ATT&CK Mapping

Each sample has a dedicated ATT&CK tab on the sample detail page showing matched MITRE ATT&CK techniques. A summary card is also shown on the Info tab.

• Click Map Techniques to scan the sample's stored analysis results and linked IOC types for known MITRE ATT&CK technique indicators.
• Results are displayed as colour-coded tactic badges arranged by tactic. Each badge shows the technique ID and name; expanding a badge shows the matched indicator evidence.
• Click a badge to open the official MITRE ATT&CK technique page in a new tab.
• Mapping covers 27 techniques across 10 tactics including execution, persistence, defence evasion, discovery, lateral movement, and impact.
• Detection uses two sources: (1) regex pattern matching against saved AnalysisResult text (excluding IOC extractor output to prevent section-header false positives), and (2) direct mapping from linked IOC types (e.g. scheduled_task → T1053, win_persistence → T1547).
• Results are persisted on the sample record and can be re-mapped at any time via the Re-map button.

STIX 2.1 Export

Vault1337 supports exporting threat intelligence in STIX 2.1 format via the stix2 library.

Sample STIX Export

On the sample detail page, the Info tab has an Export STIX button. Clicking it downloads a STIX 2.1 bundle for that sample containing:

• A Vault1337 Identity SDO as the bundle author.
• A File SCO with MD5, SHA-1, and SHA-256 hashes.
• An Indicator SDO with a hash-based STIX pattern.
• STIX objects for every linked IOC — IPv4Address, DomainName, URL, EmailAddress, WindowsRegistryKey SCOs with associated Indicator SDOs; Vulnerability SDOs for CVE IOCs; Note SDOs for persistence and other types.

Bulk IOC STIX Export

On the IOC page, select one or more IOCs using the row checkboxes, then click Export STIX in the bulk action bar. The download contains STIX objects for all selected IOCs, without being tied to a specific sample.

Decoder

Navigate to Decoder in the navigation bar to decode and transform encoded strings without uploading a sample.

Output is displayed inline — no data is sent to the server. Useful for quickly decoding obfuscated strings found during analysis.

Management Page

Navigate to Management in the navigation bar (staff accounts only) to access platform administration tools organised across multiple tabs.

Dashboard

Overview statistics for the platform: total samples, total IOCs, YARA rules, active users, and recent upload activity.

Users & Roles

• Create, edit, and deactivate user accounts without touching the Django admin.
• Assign users to roles. Built-in roles: Admin, Analyst, Read Only.
• Create custom roles and assign granular permissions to them.
• Set or reset any user's password.
• View and clear account lockouts — accounts are locked after repeated failed login attempts.

API Keys

Store third-party API keys securely in the database. Keys are written to the server's environment at runtime — they are never returned in API responses after being saved. See API Keys for the full list of supported keys.

Audit Log

• Every write action (upload, delete, tool run, role change, login, logout) is recorded in the audit log with a timestamp, username, and action detail.
• Filter the log by action type or username.
• Purge records older than the configured retention window (AUDIT_LOG_RETENTION_DAYS, default 365 days) with a single click.

Settings

View current platform settings and update runtime-configurable values without restarting the server:

• Storage paths — sample storage directory and backup directory.
• Database info — active database engine and name.
• Upload limit — maximum file upload size (configurable via MAX_UPLOAD_SIZE_MB).

SSO

Configure Single Sign-On without editing environment variables. Supported providers: Okta, Azure AD / Entra ID, Google Workspace, GitHub, and any generic OIDC provider. SSO can be enabled alongside local username/password login.

Backup

Run an on-demand pg_dump backup of the PostgreSQL database from the UI. Backup files are saved to the configured BACKUP_DIR. Backup status shows the last backup time and file path.

CyberChef

Check the locally bundled CyberChef version and update it to the latest GitHub release with a single click. No internet access is required at runtime — CyberChef is served entirely from the container.

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.

Acknowledgements

Vault1337 is built on outstanding open-source projects and public APIs.

Analysis Libraries

Backend & Framework

Intelligence APIs

Frontend

Infrastructure