Metadata-Version: 2.4
Name: anteumbra
Version: 1.0.48
Summary: Anteumbra - Web Perimeter Threat Intelligence. Passive detection, semi-active response, attacker profiling.
Author: SxyLao1
License-Expression: 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: 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<1.0.0,>=0.8.0
Requires-Dist: cachelib>=0.13.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: waitress<4.0.0,>=3.0.0
Requires-Dist: yara-python>=4.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: playwright>=1.40; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.12.0; extra == "dev"
Provides-Extra: yara
Provides-Extra: full
Requires-Dist: ssdeep; extra == "full"
Requires-Dist: py-tlsh; extra == "full"
Provides-Extra: mcp
Requires-Dist: mcp<2.0.0,>=1.12.0; extra == "mcp"

<div align="center">

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

# Anteumbra

<img src="https://img.shields.io/badge/version-1.0.48-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">

**Lightweight Web Perimeter Security**<br>
Passive detection, semi-active response, file-level forensics, and attacker profiling.

[中文](README_cn.md) | [User Manual](docs/USER_MANUAL.md) | [Architecture](docs/ARCHITECTURE.md) | [Roadmap](ROADMAP.md) | [Release Guide](docs/RELEASE.md) | [PyPI](https://pypi.org/project/anteumbra/) | [Issues](https://github.com/SxyLao1/Anteumbra/issues)

</div>

---

Anteumbra is a web perimeter threat-intelligence and WebShell detection platform for Windows and Linux. It watches website directories, detects suspicious PHP/ASP/JSP/ASPX files with YARA rules, correlates access logs, profiles attacker behavior, and provides a web dashboard for triage, quarantine, restoration, audit, and reporting.

Anteumbra is installed as one product. PyPI users and source-install developers both create runtime instances with the same `anteumbra install` and `anteumbra config` workflow.

## Operational Scope

Anteumbra is designed for one host or a small web workload: filesystem integrity monitoring, WebShell detection, local triage and response, and export to an existing security stack. It is not a replacement for an inline WAF, endpoint detection and response, a SIEM, centralized fleet management, or distributed high availability.

## Administration Model

The product currently runs with one operations administrator, similar to a single-operator host panel. The admin account supports password authentication and an optional TOTP second factor, including enrollment, login challenge, one-time recovery codes, disablement, failure handling, and audit records. User lists, role-based permissions, and multi-tenant accounts are outside the current product scope.

## Documentation

| Need | English | Chinese |
| --- | --- | --- |
| Install, configure, operate | [User Manual](docs/USER_MANUAL.md) | [用户手册](docs/USER_MANUAL_cn.md) |
| Internal architecture and extension points | [Architecture](docs/ARCHITECTURE.md) | [架构文档](docs/ARCHITECTURE_cn.md) |
| Current status and planned work | [Roadmap](ROADMAP.md) | [路线图](ROADMAP_cn.md) |
| Release history | [Changelog](CHANGELOG.md) | [更新日志](CHANGELOG_cn.md) |
| Release and PyPI publishing | [Release Guide](docs/RELEASE.md) | [发布指南](docs/RELEASE_cn.md) |
| Memory-shell response references | [Toolkit](tools/memory-shell/README.md) | [工具说明](tools/memory-shell/README_cn.md) |

## Quick Start

```bash
pip install anteumbra
anteumbra install ./anteumbra-instance
cd ./anteumbra-instance
anteumbra config wizard
anteumbra config validate
anteumbra run
```

`pip install` places package code in the active Python environment, while
`anteumbra install INSTANCE_DIR` creates an explicitly located mutable runtime
containing `config.toml`, `.env`, data, logs, rules, and quarantine files. They
are two locations for one product. Anteumbra neither creates a virtual
environment nor modifies `PATH`; install it into the Python environment you
already manage. If the `anteumbra` console command is not discoverable, use
`python -m anteumbra` with the same arguments.

Select the runtime explicitly from any working directory:

```bash
anteumbra --home /opt/anteumbra config wizard
anteumbra --home /opt/anteumbra start
```

Windows paths are accepted directly, for example
`anteumbra install E:\Software\Anteumbra`.

Open `http://127.0.0.1:8080/admin`. The default username is `admin`; the initial password is printed by `anteumbra install`. You can set a new password in `anteumbra config wizard`.

YARA scanning is included in the base install. Optional similarity engines are
available through the `full` extra:

```bash
pip install anteumbra           # includes yara-python
pip install "anteumbra[full]"  # adds ssdeep and py-tlsh
```

`anteumbra[yara]` remains accepted as a compatibility alias but adds no
dependencies beyond the base package.

## Common Configuration

Use the wizard for first-run setup:

```bash
anteumbra config wizard
anteumbra config validate
```

Use preset commands for access-log analysis. This avoids hand-writing platform-specific paths and Tomcat wildcards:

```bash
anteumbra config access-log nginx
anteumbra config access-log apache
anteumbra config access-log tomcat --base /opt/tomcat
anteumbra config access-log custom --path /path/to/access.log
anteumbra config access-log none
```

Low-level scripted edits are still available:

```bash
anteumbra config set website.path /var/www/html
anteumbra config set web_admin.port 8080
anteumbra config env set ANTEUMBRA_WECHAT_API_KEY your-send-key
anteumbra config reload
```

`config reload` fully parses the selected deployment config but does not
mutate a running service. Apply runtime changes from Web System or restart it.

Running `anteumbra config` by itself only displays subcommand help and never
creates or overwrites files. Initialization requires `anteumbra config init`;
only `config init --force` replaces an existing `config.toml` and `.env`
without prompting.

For the full command reference, see [CLI Commands](docs/USER_MANUAL.md#4-cli-commands).

## Core Capabilities

- Multi-site file monitoring on Windows and Linux
- Manual scans with scan history and printable reports
- YARA-based WebShell detection for PHP, ASP, JSP, ASPX, Godzilla, Behinder, and related families
- 27 packaged YARA files compiled independently, so one invalid custom rule file does not disable the remaining rules
- Access-log behavior analysis for Nginx, Apache, and Tomcat
- Attacker profiling, IP reputation, attack chain timelines, and cross-page batch actions
- Quarantine, restore, false-positive marking, and audit trail workflows
- JSON and SQLite storage backends with WAL support
- SIEM export in CEF, JSON Lines, and Syslog formats
- Web dashboard with merged historical/live SSE logs, runtime capability status, and configuration management
- Plugin manager and WAF/event-source integration points
- Multi-site operations in the UI: a navigation site switcher, per-site overview, and site-scoped detection, quarantine and cluster views
- Memory-shell detection, forensics and remediation for webshells that exist only in container memory, with an honest boundary for bytecode-enhancement tools
- MCP server (`anteumbra mcp serve`) plus a shipped agent skill, so a local AI agent can configure and verify a deployment
- Advanced configuration editor with a searchable TOML tree, validation, timestamped backups and version rollback
- Per-plugin configuration from the settings page, with the effective value and its source shown for every field

## Source Install

Use a source install for development, testing, or local code changes. Runtime setup remains the same as the PyPI flow.

```bash
git clone https://github.com/SxyLao1/Anteumbra.git
cd Anteumbra
pip install -e ".[dev]"
anteumbra install ./dev-instance --force
cd ./dev-instance
anteumbra config wizard
anteumbra run
```

Run tests from the repository root:

```bash
python -m pytest
```

## Development Branches

`dev` is the default branch for current development. Create `feature/*`,
`fix/*`, or `chore/*` branches from `dev`, then open a pull request back to
`dev`. Do not develop directly on `main`.

After stable validation, promote `dev` to `main` through a dedicated pull
request. The promotion must pass all required checks before merge; releases are
tagged from the resulting `main` commit. When a pull request resolves an issue,
include `Closes #N` or `Fixes #N` in its body and verify the issue is closed
after merge. Use `N/A` when no issue applies. Merged source branches are
deleted automatically by the repository setting.

See [Contributing](CONTRIBUTING.md) for the full workflow.

## Docker

```bash
docker build -t anteumbra .
docker run -d --name anteumbra \
  -p 127.0.0.1:18080:8080 \
  -e ANTEUMBRA_HOME=/var/lib/anteumbra \
  -v anteumbra-runtime:/var/lib/anteumbra \
  anteumbra
docker logs anteumbra
```

The named volume is the complete mutable runtime: `config.toml`, `.env`,
`rules`, `data`, `logs`, and `sites`. On its first start the container creates
the runtime from templates packaged in the image, permits the local Docker
gateway to reach the admin IP allowlist, and prints the initial admin password
in `docker logs`. Recreating the container with the same volume preserves
configuration, secrets, and custom rules. Existing `/app` paths remain
available for older bind-mount deployments; new deployments should mount the
complete runtime volume at `/var/lib/anteumbra`. Open
`http://127.0.0.1:18080/admin`.

For a verified backup and restore procedure, see [Release Guide](docs/RELEASE.md#docker-runtime-backup-and-restore).

## Architecture

Anteumbra follows a layered structure:

```text
src/anteumbra/
  domain/          # Entities and ports
  application/     # Use cases and orchestration
  infrastructure/  # Persistence, detection, monitoring, config, utilities
  interfaces/      # CLI, Flask blueprints, templates, static assets
```

See [Architecture](docs/ARCHITECTURE.md) for module boundaries, extension guidance, and integration contracts.

## Migration From Trident

Anteumbra is the successor to Trident. Existing `config.toml` and `data/` directories are intended to remain compatible; install Anteumbra, create a runtime instance, then copy your existing configuration and data into that instance. See the [User Manual](docs/USER_MANUAL.md) before production migration.

## License

MIT License. Third-party tools bundled under `tools/` retain their original licenses.

---

<div align="center">
  <sub>Anteumbra v1.0.48 · MIT License</sub>
</div>
