---

Philosophy & The Problem It Solves

Traditional scanning tools are inherently flawed for modern web architectures. They operate synchronously, consume excessive memory, and lack the heuristic intelligence required to bypass Next-Gen Web Application Firewalls (WAFs).

FalseAlarm was engineered from the ground up to solve this. By combining a Python asyncio orchestrator with a high-performance Go (fasthttp) worker engine, dynamic YAML vulnerability templates, and intelligent plugin auto-discovery, FalseAlarm allows operators to map vast attack surfaces at blistering speeds with streaming real-time NDJSON feedback.

Accordingly, Human-In-The-Loop (HITL) control is a core design principle of FalseAlarm. Operators retain granular control during execution with non-destructive graceful handling across all async subprocesses via Ctrl+C interrupt handlers.

---

Quickstart

To launch FalseAlarm after installation, simply type falsealarm or run a targeted scan from your CLI:

┌──(.venv)(tanh㉿kali)-[~/falsealarm]
└─$ falsealarm scan -u http://example.com/FUZZ -m dirfuzz

╭───────────────────  Layer 7 Reconnaissance Engine  ───────────────────╮
│ ___________        .__             _____  .__                         │
│ \_   _____/____    |  |   ______ _/ ____\ |  | _____ _______  _____   │
│  |    __) \__  \   |  |  /  ___/ \   __\  |  | \__  \\_  __ \/     \  │
│  |     \   / __ \_ |  |__\___ \   |  |    |  |__/ __ \|  | \/  Y Y  \ │
│  \___  /  (____  / |____/____  >  |__|    |____(____  /__|  |__|_|  / │
│      \/        \/            \/                     \/            \/  │
│                                                                       │
│ v1.0.0 | Codename: Phantom Strike                                     │
│ Asynchronous I/O Engine Active | Python 3.14.6                        │
│ Developed by reikageisme                                              │
╰─────────────────────────  Deep InfoSec Lab  ──────────────────────────╯
⚠ Legal: Only use on systems you have permission to test.

[20:44:18] [*] Starting scan: http://example.com/FUZZ
[20:44:18] [*] Engaging Go-based High Speed Fuzzing Engine...
[20:44:19] [+] Found: http://example.com/js [Status: 301, Size: 222]
[20:44:20] [+] Found: http://example.com/robots.txt [Status: 301, Size: 230]

---

Environment Variables

For leveraging private AI triage models and custom API endpoints, FalseAlarm automatically reads your configuration from .env. Create or update your .env file in the project root:

# Create local .env file
cat << 'EOF' > .env
GEMINI_API_KEY="your_google_gemini_api_key_here"
GEMINI_MODEL="gemini-3.1-pro-preview"   # optional, this is the default
OPENAI_API_KEY="your_openai_api_key_here"
ANTHROPIC_API_KEY="your_anthropic_api_key_here"
EOF

---

Core Features

Polyglot & High-Performance Engine

• Python Orchestrator + Native Go Engine: High-speed directory and parameter fuzzing powered by fasthttp in Go, with real-time NDJSON line-by-line streaming.
• Full Asynchronous I/O: Built on aiohttp and asyncio, capable of sustaining thousands of concurrent connections with minimal CPU footprint.
• Token Bucket Rate Limiting: Millisecond-precision traffic control with automatic HTTP 429 backoff handling.
• Auto-Discovery Plugin Architecture: Drop any custom .py module inheriting BaseModule into falsealarm/modules/ for instant execution without touching core code.

Stealth & Evasion

• Proxy Orchestration: Native support for chained HTTP and SOCKS5 proxies (e.g., Tor network) with automatic node health checks.
• Dynamic Fingerprinting: Automated rotation of User-Agent and HTTP headers (Accept, Accept-Language, Accept-Encoding) to blend into legitimate traffic profiles. The Go fuzzing engine now honours the same proxy, rate limit, and User-Agent as the Python core.
• Smart Catch-All & Baseline Calibration: Heuristic analysis to calculate response baselines, filtering out wildcard DNS and soft-404 traps.

Intelligence & State Management

• Multi-Target & CIDR Support: Scan individual URLs (-u), input lists (-iL targets.txt), or full IP network blocks (192.168.1.0/24).
• YAML Configuration Profiles: Save and reuse scan presets (falsealarm scan -c profile.yaml -p stealth).
• AI-Ready Triage: Direct integration with LLMs (Gemini / Anthropic / OpenAI) to automatically parse scan results and prioritize high-impact vulnerabilities.
• SQLite State Tracking: Non-blocking WAL-mode SQLite database with automatic retry timeouts for scan history and state persistence.

---

Module Ecosystem

FalseAlarm's architecture is strictly modular with dynamic plugin discovery. Each component can run in isolation or orchestrated together via the -A (All) flag.

Module Core	Tactical Capability	OPSEC Level	Status
dns	Deep Record Enumeration (A, AAAA, MX, NS, TXT, SOA, AXFR, SPF, DMARC)	Passive/Active	Production
subdomain	Subdomain Enumeration via crt.sh (OSINT) + DNS brute-force with wildcard filtering	Active	Production
httpprobe	Liveness Probing + Similarity Hashing for false positive reduction	Active	Production
tech	Fingerprinting (CMS, Frameworks, WAF, CDN) via Headers & DOM	Active	Production
dirfuzz	Polyglot (Go + Python) High-Speed Path/Directory Fuzzing (NDJSON Streaming)	Aggressive	Production
js_analysis	JavaScript scanning for hidden API endpoints & hardcoded secrets (same-origin by default)	Active	Production
cors	Strict CORS Misconfiguration Analysis & Exploit Verification	Active	Production
portscan	Async TCP/UDP Port Scanner (Nmap alternative for L7 chains)	Aggressive	Production
websocket	WebSocket (WS/WSS) Discovery & Message Fuzzing	Active	Production
vulnscan	Next-Gen YAML-based Vulnerability Detection Engine (regex/header/negative matchers + extractors)	Aggressive	Production
favicon	Favicon hashing (Shodan mmh3 + sha256) for asset pivoting	Active	Production
graphql	GraphQL endpoint discovery & introspection-exposure check	Active	Production
openredirect	Open-redirect probing across common redirect parameters	Active	Production

---

Installation

TL;DR: pipx install falsealarm and you are scanning in under a minute. The Go engine auto-downloads on first use — no Go toolchain required.

Option 1 — From PyPI (recommended)

pip install falsealarm
falsealarm scan -u example.com -q

On Debian / Kali / Ubuntu, PEP 668 blocks a system-wide pip install (externally-managed-environment). Use pipx (best for a CLI tool) or a virtual environment:

# pipx keeps FalseAlarm in its own isolated environment
pipx install falsealarm

# ...or a plain venv
python3 -m venv .venv && source .venv/bin/activate && pip install falsealarm

Optional Shodan-compatible favicon hashing:

pipx install "falsealarm[favicon]"

On first run the high-speed Go fuzzing engine auto-downloads a prebuilt binary from the latest GitHub Release. If none is available it falls back gracefully to the pure-Python fuzzing engine, so FalseAlarm always works out of the box.

Option 2 — From source (for development)

git clone https://github.com/reikageisme/falsealarm.git
cd falsealarm
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Optionally compile the Go fuzzing engine locally (else it is auto-fetched)
python -m falsealarm build-engine

Option 3 — Docker

The Dockerfile compiles the Go engine during the build automatically.

git clone https://github.com/reikageisme/falsealarm.git
cd falsealarm
docker build -t reikageisme/falsealarm .
docker run -it --rm reikageisme/falsealarm scan -u example.com -A

---

Usage Guide

The FalseAlarm CLI is built for speed and intuition.

Pre-Pentest Workflow

FalseAlarm produces a repeatable attack-surface baseline before manual testing begins. Start with the least intrusive profile and expand only when the rules of engagement authorize active enumeration.

# Fast baseline: live HTTP services and TLS/security-header posture
falsealarm scan -u example.com -q --report quick-baseline.md

# Application mapping: fingerprinting, archived URLs, JavaScript endpoints,
# CORS, WebSockets, directory discovery, and template checks
falsealarm scan -u example.com --depth deep --report attack-surface.md

# Full authorized reconnaissance: DNS, subdomains, ports, and every web module
falsealarm scan -u example.com -A --adaptive-rate --diff \
  -o falsealarm.sarif -f sarif --report pentest-handoff.md

The Markdown handoff separates automated evidence from a prioritized manual testing queue. A clean automated scan is not evidence that an application is secure; authorization, session, business-logic, and authenticated workflows still require a human tester and an intercepting proxy.

JavaScript analysis is same-origin by default to keep findings inside scope and reduce vendor-library noise. Use --include-third-party-js only when the rules of engagement explicitly include external assets or supply-chain review.

Standard Reconnaissance

# 1. Comprehensive mapping (All modules)
falsealarm scan -u example.com -A

# 2. Targeted modular scan (DNS and Tech only)
falsealarm scan -u example.com -m dns,tech

# 3. Multi-target file or CIDR range scan
falsealarm scan -iL targets.txt -q
falsealarm scan -u 192.168.1.0/24 -m portscan,httpprobe

# 4. Quick mode (Bypasses heavy fuzzing for rapid overview)
falsealarm scan -u example.com -q

Stealth & High-Speed Fuzzing

# Rate limited with Tor network proxy and randomized headers
falsealarm scan -u example.com -A -r 15 -t 20 --proxy socks5://127.0.0.1:9050 --random-agent

# High-intensity Go-accelerated Directory Fuzzing
falsealarm scan -u http://example.com/FUZZ -m dirfuzz -t 100 -w common.txt

# Recursive content discovery (dig into discovered directories)
falsealarm scan -u http://example.com -m dirfuzz --recursion-depth 2

Pipe Mode & Tool Chaining (NDJSON)

FalseAlarm reads targets from stdin and streams NDJSON results to stdout with --pipe (logs go to stderr), so it composes with the rest of your toolkit:

# Chain FalseAlarm stages together
echo example.com | falsealarm --pipe -m httpprobe | jq -r .url \
  | falsealarm --pipe -m tech,vulnscan

# Feed it from other recon tools
subfinder -d example.com | falsealarm --pipe -m httpprobe -o live.jsonl -f jsonl

Data Management & Profiles

# Load scan parameters from a YAML profile
falsealarm scan -c profile.yaml -p stealth

# Export results to JSON for CI/CD pipelines
falsealarm scan -u example.com -A -o results.json -f json

# Export SARIF for GitHub Code Scanning and security CI pipelines
falsealarm scan -u example.com -A -o falsealarm.sarif -f sarif

# Produce a pentester handoff with attack surface, priorities, and a manual test queue
falsealarm scan -u example.com -A --report pentest-report.md

# List historical scans
falsealarm list-scans

# Inspect every installed module before choosing a scan profile
falsealarm modules

# Continue a scan that was interrupted or paused
falsealarm scan --resume <scan-id>

---

AI Triage Integration

FalseAlarm introduces an AI Triage layer. By hooking into Gemini / OpenAI / Anthropic LLMs, the framework automatically analyzes scan outputs, filters out noise, and highlights chained exploit paths.

Execute scan with AI Triage:

falsealarm scan -u example.com -A --ai-triage

The default triage model is gemini-3.1-pro-preview. Override it with the GEMINI_MODEL environment variable — for example gemini-3.8-flash for cheaper, faster triage:

GEMINI_MODEL=gemini-3.8-flash falsealarm scan -u example.com -A --ai-triage

---

Python API Integration

FalseAlarm is fully extensible. You can import its async core directly into your own security orchestration scripts.

import asyncio
from falsealarm.core.config import ScanConfig
from falsealarm.core.engine import AsyncEngine
from falsealarm.modules.techdetect import TechDetectModule

async def automate_recon():
    # 1. Define scanning parameters
    config = ScanConfig(
        target="example.com",
        modules=["tech"],
        threads=20,
        timeout=10
    )
    
    # 2. Initialize the asynchronous networking core
    engine = AsyncEngine(config)
    
    # 3. Instantiate and execute the specific module
    module = TechDetectModule(config, engine)
    results = await module.run()
    
    print(f"[+] Discovered Technologies: {results}")
    await engine.close()

if __name__ == "__main__":
    asyncio.run(automate_recon())

---

Contributing

We welcome contributions from the InfoSec community. Whether it's adding new YAML vulnerability templates, optimizing the async core, or fixing bugs, please review our CONTRIBUTING.md guidelines before submitting a Pull Request.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See CODE_OF_CONDUCT.md.

---

License

Copyright (c) 2026 ReiKage (reikageisme) & FalseAlarm Security Engine Contributors.

This project is a combination of open-source components under the MIT License (see LICENSE-MIT) and framework additions licensed under the Research & Security Assessment License (see LICENSE).

---

Legal Disclaimer & Ethics

FalseAlarm is an offensive security tool designed strictly for authorized penetration testing, academic research, and lawful bug bounty programs.

Executing Layer 7 reconnaissance and fuzzing attacks against infrastructure without explicit, written authorization is illegal. The developers assume zero liability for any misuse, damage, or legal consequences resulting from the deployment of this tool.

Hack ethically. Stay authorized.