ThreatDeck

Terminal-based threat intelligence monitoring and alerting platform
for SOCs, security researchers, and threat intelligence analysts

---

Demo

Dashboard Preview

Feeds Preview

Alerts Preview

Articles Preview

Keywords Preview

Tags Preview

Features

• Multi-source Feed Management — Aggregate threat intelligence from APIs, RSS/Atom feeds, website scraping, and .onion sites via Tor
• JSONPath API Templates — Extract structured data from JSON APIs using configurable JSONPath expressions for title, description, date, URL, and source fields
• Keyword Matching — Simple text or regex-based keyword matching with 4 criticality levels (Low, Medium, High, Critical)
• Alert Generation — Automatic alert creation with deduplication (content hashing), snippet extraction, and metadata preservation
• Cached Article Feed — Browse every cached feed item across RSS/API sources and read cleaned article text directly in the terminal
• IOC Extraction and Enrichment — Extract IOCs from alerts and feed items, store occurrence history, queue local enrichment, and display reputation/risk in the TUI
• Tagging System — Organize feeds, keywords, and alerts with color-coded custom tags
• Notifications — Send alerts via Email (SMTP), Webhook, or Discord with per-channel minimum criticality thresholds and IOC summaries
• Dashboard Overview — At-a-glance statistics, criticality distribution, recent alerts, and 7-day trend visualization
• Feed Health Monitoring — Track consecutive failures, health status (Healthy/Warning/Error/Disabled), and detailed health logs
• Settings Management — Alert retention policies, theme selection, notification channel configuration
• 5 Built-in Themes — dark, light, solarized, dracula, monokai

Installation

Using Cargo

cargo install ThreatDeck

The binary will be installed as ThreatDeck in your Cargo bin directory (usually ~/.cargo/bin/).

Build from Source

git clone https://github.com/gripebomb/ThreatDeck.git
cd ThreatDeck

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Binary location
target/release/ThreatDeck

Quick Start

First Run

On first launch, ThreatDeck automatically creates its configuration and data directories:

ThreatDeck

Default paths:

• Config: ~/.config/ThreatDeck/config.toml
• Database: ~/.local/share/ThreatDeck/ThreatDeck.db

To view the exact paths on your system:

ThreatDeck --config-paths

Adding Feeds

1. Launch the application: ThreatDeck
2. Press 2 to navigate to the Feeds screen
3. Press a to add a new feed
4. Fill in the feed details (Tab to cycle fields, Enter to save):
   • Name: Descriptive name for the feed
   • URL: Feed endpoint URL
   • Type: API, RSS, Website, or Onion
   • Interval: Polling interval in seconds (minimum 60)
   • For API feeds: select an API template and optionally provide an API key
   • For Onion feeds: configure Tor proxy (e.g., socks5h://127.0.0.1:9050)

Creating Keywords

1. Press 7 to navigate to the Keywords screen
2. Press a to add a keyword
3. Configure:
   • Pattern: Text or regex pattern to match
   • Type: Simple text or Regex
   • Case Sensitive: Whether matching is case-sensitive
   • Criticality: Low, Medium, High, or Critical
4. Press t to test a pattern against sample input before saving

Viewing Alerts

1. Press 3 to navigate to the Alerts screen
2. Browse alerts with j/k or arrow keys
3. Press r to toggle read/unread status
4. Press R to mark all alerts as read
5. Press d to delete an alert, D for bulk delete mode

Configuration

The configuration file is stored at ~/.config/ThreatDeck/config.toml:

theme = "dark"                    # dark, light, solarized, dracula, monokai
alert_retention_days = 30         # Auto-delete alerts older than N days
dashboard_refresh_secs = 30       # Dashboard data refresh interval
tick_rate_ms = 250                # UI tick rate (lower = more responsive)
max_health_log_entries = 100      # Maximum feed health log entries to retain

[ioc]
enabled = true
extract_from_raw_json = true
max_indicators_per_content_item = 250

[enrichment]
enabled = true
enrich_only_alert_indicators = false

Enrichment Providers

ThreatDeck seeds local provider records for CISA KEV and URLHaus.

• cisa-kev is enabled by default and uses a local cisa-kev.json cache in the ThreatDeck data directory.
• urlhaus is disabled by default because it sends selected URL, domain, IPv4, MD5, and SHA256 indicators to the external URLHaus API.

To use URLHaus, create a free URLHaus Auth-Key, export it before starting ThreatDeck, then enable the provider:

export URLHAUS_AUTH_KEY="your-auth-key"
ThreatDeck --enable-provider urlhaus
ThreatDeck --enrich-once

The Settings screen provider health check reports whether URLHAUS_AUTH_KEY is available.

Theme Settings

Change themes dynamically via the Settings screen (0) or edit config.toml directly:

Theme	Description
dark	Default dark theme with muted palette
light	Clean light theme for bright terminals
solarized	Ethan Schoonover's Solarized Dark
dracula	Popular Dracula color scheme
monokai	Classic Monokai syntax highlighting theme

Feed Types

API (with JSONPath Templates)

For JSON REST APIs, use JSONPath expressions to extract fields. Two templates are built in:

Template	Title Path	Description Path	Date Path	URL Path
Ransomfeed.it	$.post_title	$.description	$.discovered	$.source
RansomLook	$.name	$.description	$.published	$.url

Create custom templates via SQL or API. The pagination_config field supports offset/limit and page-based pagination strategies.

Example API feed configuration:

• URL: https://api.ransomfeed.it/v1/posts
• Type: API
• Template: Ransomfeed.it
• Interval: 300 (5 minutes)

RSS / Atom

Standard RSS 2.0 and Atom 1.0 feeds are automatically parsed. Simply provide the feed URL and select type RSS.

Example RSS feeds:

• https://feeds.securityweek.com/securityweek
• https://www.bleepingcomputer.com/feed/

Website Scraping

For HTML pages without structured feeds, the scraper extracts text content from the page body for keyword matching. Provide the target URL and select type Website.

Example:

• URL: https://www.cisa.gov/news-events/cybersecurity-advisories
• Type: Website
• Interval: 600 (10 minutes)

Onion / Tor

Access .onion threat intelligence sources via a Tor SOCKS5 proxy. Configure the Tor proxy address (default: socks5h://127.0.0.1:9050) and provide an .onion URL.

Requirements: Tor must be running locally with a SOCKS5 listener.

Example:

• URL: http://ransomxifxwc5ste.onion/posts
• Type: Onion
• Tor Proxy: socks5h://127.0.0.1:9050

Keyboard Shortcuts

Global Keys

Key	Action
1	Dashboard screen
2	Feeds screen
3	Alerts screen
4	Articles screen
5	Indicators screen
6	Enrichment Queue screen
7	Keywords screen
8	Tags screen
9	Logs screen
0	Settings screen
q	Quit application
? / F1	Toggle help overlay
Esc	Cancel current action / Go back

Dashboard

Key	Action
r	Refresh dashboard data
1-9,0	Navigate to other screens

Feeds

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
a / n	Add new feed
e	Edit selected feed
d	Delete selected feed (with confirmation)
m	Trigger manual fetch
t	Assign tags to feed
Enter	View feed details
Space	Toggle feed enabled/disabled
/	Filter feeds
s	Cycle sort order

Alerts

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
r	Toggle read/unread status
R	Mark all alerts as read
d	Delete selected alert
D	Enter bulk delete mode
t	Assign tags to alert
/	Filter alerts

Bulk Mode (after pressing D):

Key	Action
Space	Toggle selection of current alert
a	Select all alerts
d	Delete selected alerts
Esc	Exit bulk mode

Articles

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
Enter	Fetch full text if needed, then open reader
r	Toggle read/unread status
u	Toggle unread-only filter
/	Filter cached articles
Esc	Close article reader

Indicators

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
e	Queue enrichment for selected indicator
t	Cycle IOC type filter
c	Clear IOC type filter
r	Refresh indicators
/	Search indicator values

Enrichment Queue

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
p	Process a batch of pending jobs
r	Refresh queue
/	Filter queue rows

Keywords

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
a / n	Add new keyword
e	Edit selected keyword
d	Delete selected keyword
t	Test pattern against sample input
Enter	Toggle keyword enabled/disabled

Tags

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
a / n	Add new tag
e	Edit selected tag
d	Delete selected tag

Logs

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up

Settings

Key	Action
Tab	Switch General/Notifications/Enrichment tabs
i	Toggle IOC extraction in General tab
j	Toggle raw JSON extraction in General tab
e	Toggle enrichment queueing in General tab
o	Toggle alert-only enrichment in General tab
Space / e	Toggle selected provider in Enrichment tab
t	Test selected provider in Enrichment tab

Forms (Add/Edit)

Key	Action
Tab	Next field
Shift+Tab	Previous field
Enter	Save
Esc	Cancel and close form

Architecture Overview

ThreatDeck/
├── src/
│   ├── main.rs           # CLI args, terminal setup, main event loop
│   ├── app.rs            # Application state, screen navigation, key routing
│   ├── config.rs         # Config file (TOML) loading and saving
│   ├── db.rs             # SQLite database operations (rusqlite)
│   ├── types.rs          # Core data structures and enums
│   ├── theme.rs          # Color theme definitions
│   ├── schema.sql        # Database schema with default data
│   ├── scheduler.rs      # Background feed polling scheduler
│   ├── notify.rs         # Notification channels (Email, Webhook, Discord)
│   ├── alert.rs          # Alert processing and deduplication logic
│   ├── enrichment.rs     # Enrichment worker orchestration
│   ├── keyword.rs        # Keyword matching engine (text + regex)
│   ├── tag.rs            # Tag management
│   ├── template.rs       # API template management
│   ├── ai.rs             # AI/ML analysis integration placeholder
│   ├── feed/             # Feed processing modules
│   │   ├── mod.rs        # Feed dispatcher and common types
│   │   ├── api.rs        # JSON API feed fetcher with JSONPath
│   │   ├── rss.rs        # RSS/Atom feed parser
│   │   ├── web.rs        # Website HTML scraper
│   │   ├── onion.rs      # Tor/onion site fetcher
│   │   └── utils.rs      # Feed utility functions
│   └── ui/               # TUI rendering modules
│       ├── mod.rs        # Main draw dispatcher, help, notifications
│       ├── dashboard.rs  # Stats, pie chart, recent alerts, trend
│       ├── feeds.rs      # Feed list, add/edit form
│       ├── alerts.rs     # Alert list, bulk operations, IOC panel
│       ├── articles.rs   # Cached article reader with IOC panel
│       ├── indicators.rs # Indicator search and detail page
│       ├── enrichment_queue.rs # Enrichment queue monitor
│       ├── keywords.rs   # Keyword list, test mode
│       ├── tags.rs       # Tag management screen
│       ├── logs.rs       # Feed health log viewer
│       ├── settings.rs   # General settings and notifications
│       └── utils.rs      # UI helper functions
├── Cargo.toml
└── README.md

Key Design Decisions

• SQLite (bundled): Self-contained database with no external dependencies; rusqlite with bundled feature ensures consistent builds across platforms
• ratatui + crossterm: Cross-platform terminal UI framework with async event handling
• JSONPath for APIs: Declarative data extraction without custom parsers per feed
• Content Hashing: SHA-256-based deduplication prevents duplicate alerts from the same content
• Queued Enrichment: IOC enrichment uses an outbox-style queue so feed ingestion stays fast and resilient
• Modular Feed Engine: Each feed type implements a common interface, making it easy to add new sources

Development

Prerequisites

• Rust 1.75+ with Cargo
• sqlite3 CLI (for demo-seed.sh)

Building

# Debug build
cargo build

# Release build with optimizations
cargo build --release

# Run with cargo
cargo run

# Run and print config paths
cargo run -- --config-paths

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

Code Quality

# Format check
cargo fmt --check

# Apply formatting
cargo fmt

# Run Clippy lints
cargo clippy -- -D warnings

# Run Clippy with all features
cargo clippy --all-targets --all-features -- -D warnings

Seeding Demo Data

A helper script is provided to populate the database with realistic demo data:

# Uses default database path
./demo-seed.sh

# Or specify a custom database path
./demo-seed.sh /path/to/custom.db

This creates 6 feeds, 8 keywords, 15 alerts, and tag assignments for testing and demonstration.

Database Schema

The application uses the following SQLite schema (see src/schema.sql):

• feeds — Feed sources with health tracking
• api_templates — JSONPath extraction templates
• keywords — Matching patterns with criticality levels
• alerts — Generated alerts with deduplication hashes
• tags — Color-coded labels
• feed_tags / keyword_tags / alert_tags — Many-to-many tag assignments
• notifications — Notification channel configurations
• feed_health_logs — Per-feed health status history
• indicators / indicator_occurrences / alert_indicators — Extracted IOC records and source links
• enrichment_providers / enrichment_jobs / enrichment_results — Provider configuration, queued jobs, and normalized enrichment output

Upcoming Features

• Additional enrichment providers (AbuseIPDB, GreyNoise, VirusTotal, RDAP, DNS)
• Terminal-native case management
• Watchlists for organizations/domains/VIPs
• Threat actor profiles
• Rule testing against historical content
• Markdown report export
• Command palette
• Local LLM alert summaries

License

This project is licensed under the MIT License.

---

Built with ratatui and Rust.