Scan Hacker News for security-related content in any timeframe. 38 targeted keyword queries cover CVEs, exploits, ransomware, breaches, zero-days, threat actors, infrastructure vulns, and more. Deduplicates, classifies by severity, and generates terminal + markdown + JSON reports.
Zero dependencies — stdlib only. Concurrent by default.
# Install
pip install --break-system-packages -e .
hns --install # Write default config to ~/.config/hns/
# Basic usage
hns # Last 7 days, terminal output
hns -d 2026-05-01 # Since May 1
hns -s 2026-05-01 -e 2026-05-31 # Specific month
hns -d 2026-05-01 -o report.md # Markdown export
hns -d 2026-05-01 -o data.json # JSON export
# Performance tuning
hns -d 2026-05-01 --threads 10 # 10 concurrent API requests
hns -d 2026-05-01 --no-cache # Skip cache, always fetch fresh
hns --cache-stats # Show cache size/hits
# Filtering
hns -m 5 # Only stories with 5+ points
hns --min-comments 10 # Only stories with 10+ comments
hns --exclude "bitcoin,crypto" # Exclude keyword matches
hns --enrich # Fetch live HN comment counts
# Output control
hns --text # Show story snippets in terminal
hns --max-show 100 # Show up to 100 stories
hns --summary-only # Just the stats, no story list38 keyword queries in 7 categories, each 1-4 tightly-related terms (Algolia uses AND semantics):
| Category | Queries | Examples |
|---|---|---|
| CVE / Vuln | 4 | CVE, vulnerability, "critical vulnerability" RCE, "zero day" 0day |
| Exploitation | 8 | exploit, RCE, "SQL injection" XSS CSRF, "container escape" |
| Threat Intel | 8 | ransomware, breach, "supply chain attack", APT, backdoor |
| Infra / Network | 8 | "kernel vulnerability", OpenSSL libcurl, "BGP hijack", DDoS |
| Disclosure | 4 | "bug bounty", "security research", "cloud security", "iOS vulnerability" |
| Advisories | 3 | "security patch", "emergency patch", CISA "known exploited" |
| Broad Catch | 3 | infosec cybersecurity, hacked compromised, "cryptographic attack" |
Concurrent execution — ThreadPoolExecutor with configurable thread count. 10 threads = ~10x faster than sequential.
Disk caching — API responses cached to ~/.cache/hns/ with configurable TTL. Second scan on same date range is nearly instant.
Retry logic — Automatic retry with exponential backoff on HTTP errors (3 retries by default, 429 handling with backoff).
Severity classification — Keyword-based scoring into critical/high/medium/low with categories (vuln/exploit/threat/patch/disclosure).
hns --install # Creates ~/.config/hns/config.yamlscanner:
hits_per_page: 200
max_pages_per_query: 5
request_delay: 0.6 # Delay between page requests
concurrent_requests: 5 # Thread pool size
timeout: 15 # HTTP timeout seconds
retries: 3 # Retry count on failure
output:
min_points: 1
max_show: 50
max_results: 2000
cache:
enabled: true
dir: ~/.cache/hns
ttl_hours: 24
filters:
exclude_domains: "example.com,foo.org"
exclude_keywords: "crypto,bitcoin,nft"
extra_queries:
my-org: "MyCompany MyProduct vulnerability"hns [options] Run a security scan
hns --install Write default config
hns --clear-cache Clear all cached API responses
hns --clear-cache-older 48 Clear cache entries older than 48 hours
hns --cache-stats Show cache directory size and file count
hn-security-report/
├── pyproject.toml # Package metadata + console_scripts entry point
├── main.py # Shebang entry: ./main.py -d 2026-06-01
├── hns/
│ ├── cli.py # Argparse CLI (200+ lines, all flags)
│ ├── scanner.py # Core engine: concurrent search, caching, retries
│ ├── keywords.py # 38 query definitions + severity classifier
│ ├── report.py # Terminal color + markdown + JSON output
│ ├── config.py # YAML-free config loader (~/.config/hns/config.yaml)
│ └── cache.py # JSON-file disk cache with TTL
├── README.md
└── .gitignore
Uses the public HN Algolia API. With caching enabled, repeated scans of the same date range hit disk instead of the network. A fresh 30-day scan makes ~190 API calls (38 queries × up to 5 pages), completing in 10-15 seconds with 10 threads.