Skip to main content
Anteumbra

Anteumbra

Version Python Platform License

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

中文 | User Manual | Architecture | Roadmap | Release Guide | PyPI | Issues


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 用户手册
Internal architecture and extension points Architecture 架构文档
Current status and planned work Roadmap 路线图
Release history Changelog 更新日志
Release and PyPI publishing Release Guide 发布指南
Memory-shell response references Toolkit 工具说明

Quick Start

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:

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:

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:

anteumbra config wizard
anteumbra config validate

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

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:

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.

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.

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:

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 for the full workflow.

Docker

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.

Architecture

Anteumbra follows a layered structure:

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 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 before production migration.

License

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


Anteumbra v1.0.48 · MIT License

Metadata

Release files for anteumbra 1.0.48

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anteumbra 1.0.48
File Size Uploaded Provenance Actions
anteumbra-1.0.48.tar.gz 767.6 kB With provenance Details for anteumbra-1.0.48.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anteumbra 1.0.48
File Interpreter ABI Platform Actions
anteumbra-1.0.48-py3-none-any.whl Python 3 none any Details for anteumbra-1.0.48-py3-none-any.whl

Total release size: 1.7 MB

Release files / anteumbra-1.0.48.tar.gz

Download URL anteumbra-1.0.48.tar.gz
Size 767.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a02ad3ebfeb4bd0b24148153e892a1a9d763e05798609e26b65d68e7514e8b05
BLAKE2b-256 checksum
How to use checksums
2004214b5cd4ebff1ddbcbd0755f92339c263d4b53664d4fb629f698d4645e67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / anteumbra-1.0.48-py3-none-any.whl

Download URL anteumbra-1.0.48-py3-none-any.whl
Size 913.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
03c4f73c2c64e66997341c7d39ba55f0974a7a741f9ed2bfd8741059d303644f
BLAKE2b-256 checksum
How to use checksums
6447c80dc72134573c6ae7cbb6abe4f8598f691431d060bf53e5121979462160
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Security for anteumbra 1.0.48

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anteumbra-1.0.48.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.48 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page