Anteumbra

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 13 Open GitHub ↗

WebShell Detector

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Anteumbra

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

</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.

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

## 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 \
  -v $(pwd)/anteumbra-data:/app/data \
  -v $(pwd)/anteumbra-logs:/app/logs \
  anteumbra
docker logs anteumbra
```

The container starts the same full runtime as `anteumbra run`, creates a
Docker-friendly default config on first start, permits the local Docker gateway
to reach the admin IP allowlist, and prints the initial admin password in
`docker logs`. Open `http://127.0.0.1:18080/admin`.

## 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.35 · MIT License</sub>
</div>

Anteumbra

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README