Metadata-Version: 2.4
Name: falsealarm
Version: 1.0.4
Summary: Async Web Reconnaissance Engine for Pentesters & Bug Bounty Hunters
Author: reikageisme
License: MIT
Project-URL: Homepage, https://github.com/reikageisme/falsealarm
Project-URL: Repository, https://github.com/reikageisme/falsealarm
Project-URL: Issues, https://github.com/reikageisme/falsealarm/issues
Keywords: pentesting,reconnaissance,security,bug-bounty
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-MIT
Requires-Dist: aiohttp>=3.9
Requires-Dist: aiohttp-socks>=0.8
Requires-Dist: typer[all]>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: dnspython>=2.6
Requires-Dist: websockets>=12.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: pyyaml>=6.0
Requires-Dist: certifi
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: favicon
Requires-Dist: mmh3>=4.0; extra == "favicon"
Provides-Extra: all
Requires-Dist: mmh3>=4.0; extra == "all"
Dynamic: license-file

<div align="center">
  <picture>
    <source srcset="assets/Falsealarm.png" media="(prefers-color-scheme: dark)">
    <source srcset="assets/Falsealarm.png" media="(prefers-color-scheme: light)">
    <img src="assets/Falsealarm.png" alt="FalseAlarm Logo" width="600" style="image-rendering: -webkit-optimize-contrast; image-rendering: crisp-edges;">
  </picture>

  <br/>
  <h1>FalseAlarm: Advanced Async Web Reconnaissance Framework</h1>
  <p><strong>An out-of-the-box, Polyglot (Python + Go) & AI-Ready Attack Surface Mapping Engine.</strong></p>

  <p>
    <a href="https://pypi.org/project/falsealarm/"><img src="https://img.shields.io/pypi/v/falsealarm?style=for-the-badge&logo=pypi&logoColor=white&color=2563eb" alt="PyPI version" /></a>
    <a href="https://pypi.org/project/falsealarm/"><img src="https://img.shields.io/pypi/dm/falsealarm?style=for-the-badge&color=8b5cf6&label=downloads" alt="PyPI downloads" /></a>
    <a href="https://github.com/reikageisme/falsealarm/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-16a34a.svg?style=for-the-badge" alt="license" /></a>
    <a href="https://github.com/reikageisme/falsealarm/stargazers"><img src="https://img.shields.io/github/stars/reikageisme/falsealarm?style=for-the-badge&color=eab308" alt="stars" /></a>
    <a href="https://github.com/reikageisme/falsealarm/network/members"><img src="https://img.shields.io/github/forks/reikageisme/falsealarm?style=for-the-badge&color=blue" alt="forks" /></a>
    <a href="https://github.com/reikageisme/falsealarm/issues"><img src="https://img.shields.io/github/issues/reikageisme/falsealarm?style=for-the-badge&color=e67e22" alt="open issues" /></a>
    <img src="https://img.shields.io/badge/python-3.10+-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python Version">
    <img src="https://img.shields.io/badge/go-1.20+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go Version">
  </p>

  <p>
    <em>Developed by <a href="https://github.com/reikageisme">ReiKage (reikageisme)</a> & The Open Source InfoSec Community.</em>
  </p>

  <a href="#philosophy--the-problem-it-solves">Philosophy</a> •
  <a href="#quickstart">Quickstart</a> •
  <a href="#core-features">Features</a> •
  <a href="#module-ecosystem">Modules</a> •
  <a href="#installation">Installation</a> •
  <a href="#environment-variables">Environment</a> •
  <a href="#usage-guide">Usage Guide</a> •
  <a href="#ai-triage-integration">AI Triage</a> •
  <a href="#contributing">Contributing</a> •
  <a href="CHANGELOG.md">Changelog</a> •
  <a href="#license">License</a>
</div>

---

## 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:

```text
┌──(.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:

```bash
# 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)

```bash
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:

```bash
# 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:

```bash
pipx install "falsealarm[favicon]"
```

> On first run the high-speed Go fuzzing engine auto-downloads a prebuilt
> binary from the latest [GitHub Release](https://github.com/reikageisme/falsealarm/releases).
> 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)

```bash
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.

```bash
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.

```bash
# 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
```bash
# 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
```bash
# 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:

```bash
# 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
```bash
# 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:**
```bash
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:

```bash
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.

```python
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](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](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](LICENSE-MIT)) and framework additions licensed under the **Research & Security Assessment License** (see [LICENSE](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.*
