Metadata-Version: 2.4
Name: anteumbra
Version: 1.0.6
Summary: Anteumbra — Web Perimeter Threat Intelligence. Passive detection, semi-active response, attacker profiling.
Author: SxyLao1
License: MIT
Project-URL: Homepage, https://github.com/SxyLao1/Anteumbra
Project-URL: Repository, https://github.com/SxyLao1/Anteumbra.git
Project-URL: Issues, https://github.com/SxyLao1/Anteumbra/issues
Keywords: webshell,security,detection,yara,waf,forensics,threat-intel,profiling
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Internet :: Log Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: flask<3.0.0,>=2.3.3
Requires-Dist: flask-wtf>=1.2.1
Requires-Dist: flask-session>=0.5.0
Requires-Dist: flask-babel>=3.1.0
Requires-Dist: wtforms>=3.1.2
Requires-Dist: watchdog>=3.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.32.3
Requires-Dist: psutil>=5.9.8
Requires-Dist: tomli>=2.0.1
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: urllib3>=2.2.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: gunicorn>=22.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: playwright>=1.40; extra == "dev"
Provides-Extra: yara
Requires-Dist: yara-python>=4.3.0; extra == "yara"
Provides-Extra: full
Requires-Dist: yara-python>=4.3.0; extra == "full"
Requires-Dist: ssdeep; extra == "full"
Requires-Dist: py-tlsh; extra == "full"

<div align="center">

<img src="assets/anteumbra-logo.svg" width="120" alt="Anteumbra">

# Anteumbra

<img src="https://img.shields.io/badge/version-1.0.6-blue?style=flat-square" alt="Version">
<img src="https://img.shields.io/badge/python-3.10%2B-green?style=flat-square" alt="Python">
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey?style=flat-square" alt="Platform">
<img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="License">
<img src="https://img.shields.io/badge/tests-217%2F217-brightgreen?style=flat-square" alt="Tests">

**Lightweight Web Perimeter Security** — Passive Detection · Semi-Active Response · File-Level Forensics

> *"Anteumbra is an annular eclipse observatory at the web perimeter. Every ray that tries to pierce the boundary is recorded, measured, and traced back to its source. Disguised threats reveal themselves in their own blazing intensity."*

[中文文档](README_zh.md) | [PyPI](https://pypi.org/project/anteumbra/) | [Issues](https://github.com/SxyLao1/Anteumbra/issues)

</div>

---

Anteumbra (formerly Trident) is a production-grade **web perimeter threat intelligence** system for Linux and Windows. It monitors file system changes in real time, detects WebShells using an embedded YARA rule engine, profiles attacker behavior, and provides a web-based management dashboard — all without inline blocking. Think of it as a **security observatory** at the boundary layer.

Key capabilities:

- **Real-time file monitoring** — Linux Inotify / Windows ReadDirectoryChangesW adaptive switching
- **Manual scanner** — Active directory scanning with SSE real-time progress, scan history, printable reports
- **YARA rule engine** — 18+ rule files covering PHP, ASP, JSP, ASPX, Godzilla, Behinder; hot-reload supported
- **Threat profiling** — Attacker behavior clustering via UA/time-bucket, IP pool merging, decay engine
- **File similarity clustering** — ssdeep/TLSH/SimHash hash engine with 0.80 threshold grouping
- **IP block ledger** — Audit trail for all block/unblock operations, inline note editing, JSON/CSV export
- **Bidirectional linking** — Profile ↔ Records ↔ Quarantine cross-navigation, attack chain timeline
- **Log heuristic engine** — Behavior-level detection: brute force, scanner, error storm, tool signature, suspicious path
- **Memory shell detection** — Java/ASP.NET reference tools + access log tracer for WebShell origin correlation
- **Batch operations** — Cross-page multi-select for Records/Quarantine with batch quarantine/restore/delete
- **SIEM export** — CEF/JSON Lines/Syslog formats with file rotation and real-time UDP streaming
- **Plugin system** — Config-driven plugin manager with lifecycle, event dispatch, 4 WAF adapters
- **Dual storage** — JSON + SQLite (WAL mode, FK constraints, indexed) with configurable backend switching
- **WAL transaction logs** — Async batch writes with auto rotation, minimal data loss under file locking
- **Smart alerting** — Exponential backoff with adaptive thresholds to reduce false positives
- **Web dashboard** — Dark theme terminal-style interface, SSE real-time log stream, HTMX-driven, SPA navigation
- **Enterprise security** — CSRF protection, IP whitelist, Scrypt password hashing, static JS auth guard
- **Production deployment** — Docker multi-stage build, Gunicorn multi-worker, systemd service, `pip install -e .`
- **Comprehensive test suite** — ~217 tests: 88 unit + 94 E2E backend + 34 E2E UI (Playwright) + 1 WAF proxy

## Quick Start

```bash
pip install anteumbra
anteumbra --help
```

### From Source

```bash
git clone https://github.com/SxyLao1/Anteumbra.git
cd Anteumbra
pip install -e .
python -m pytest tests/core/ -v
```

### Windows

```powershell
git clone https://github.com/SxyLao1/Anteumbra.git
cd Anteumbra
.\run_tests.bat
```

### Docker

```bash
docker build -t anteumbra .
docker run -d -p 8080:8080 -v $(pwd)/data:/app/data -v $(pwd)/config.toml:/app/config.toml anteumbra
```

Docker Compose:

```yaml
services:
  anteumbra:
    build: .
    ports: ["8080:8080"]
    volumes:
      - ./data:/app/data
      - ./config.toml:/app/config.toml
    restart: unless-stopped
```

The Docker image includes all three hash engines (ssdeep + py-tlsh + yara-python) compiled and active for Linux.

Then open `http://127.0.0.1:5000/admin`. Default username is `admin`; password is printed in the console during first setup.

## Architecture

```
src/anteumbra/
├── domain/               # Domain layer: entities + ports (Plugin, Repository, Detector, Notifier, EventSource)
├── application/          # Application layer: PluginManager (lifecycle, event dispatch)
├── infrastructure/       # Infrastructure: persistence (JSON/SQLite), detection, monitoring, config, utils
└── interfaces/           # Interfaces: Flask blueprints, templates, static assets
```

Architecture follows Domain-Driven Design with four separated layers. Event-driven architecture (EDA) covers 85%+ of the data flow via implicit event bus (PluginManager with emit/dispatch semantics). SQLite storage layer features foreign key constraints (ON DELETE SET NULL) and 13 indexed columns.

## Ecosystem & Related Projects

Anteumbra is designed to complement these excellent open-source tools:

**Memory Shell Detection**:
- [c0ny1/java-memshell-scanner](https://github.com/c0ny1/java-memshell-scanner) — JSP-based Tomcat/Jetty/WebLogic scanner
- [yzddmr6/As-Exploits](https://github.com/yzddmr6/As-Exploits) — ASP.NET memory shell scanner
- [private-xss/memory-shell-detector](https://github.com/private-xss/memory-shell-detector) — Java GUI+CLI detector (MIT)

**WAF / Log Analysis**:
- [SpiderLabs/ModSecurity](https://github.com/SpiderLabs/ModSecurity) — WAF engine
- [SpiderLabs/owasp-modsecurity-crs](https://github.com/SpiderLabs/owasp-modsecurity-crs) — OWASP Core Rule Set

**Hashing & Similarity**:
- [ssdeep-project/ssdeep](https://github.com/ssdeep-project/ssdeep) — CTPH fuzzy hashing
- [trendmicro/tlsh](https://github.com/trendmicro/tlsh) — Trend Micro Locality Sensitive Hash

## Tools

The `tools/` directory includes:

- **WAF Proxy** (`tools/waf_proxy/`) — Lightweight HTTP reverse proxy with built-in WAF rules (SQLi, XSS, traversal, webshell upload, command injection). Generates attack events in JSON Lines format for the threat profiling engine. Useful for testing and development.

```bash
python tools/waf_proxy/waf_proxy.py            # :8081 → :80
python tools/waf_proxy/waf_proxy.py 8081 8080  # custom ports
```

## Migration from Trident

Anteumbra is the successor to [Trident](https://github.com/SxyLao1/Trident) (v1.9.5). If you were using Trident:

```bash
# 1. Uninstall Trident
cd Trident
.\uninstall.bat      # Windows
# bash uninstall.sh  # Linux

# 2. Install Anteumbra
pip install anteumbra

# 3. Copy your config and data
cp /path/to/Trident/config.toml /path/to/Anteumbra/
cp -r /path/to/Trident/data/ /path/to/Anteumbra/
```

Your `config.toml` and `data/` directory are compatible.

## License

MIT License. Free for production, academic research, and personal use.

Third-party tools bundled in `tools/` retain their original licenses.

---

<div align="center">
  <sub>Anteumbra v1.0.6 — MIT License</sub>
</div>
