beescan - Modular platform for security auditing of networks

项目说明

🛡️ BeeScan

BeeScan is a modular platform for comprehensive IT infrastructure security auditing. It supports integration of external tools as plugins, automated result collection and structuring, multi-format report generation, and flexible centralized configuration. The architecture enables analysis of networks, web applications, DNS, and APIs, and is scalable for any De, penetration testing, or monitoring tasks.

Key Features

Plugin support — 5 tools integrated.

Plug-and-Play architecture — each tool is a separate parser module.

PostgreSQL output and report rendering from the database.

Tool profiles — choose scan level per tool.

Report generation: TERMINAL, HTML, PDF.

Docker isolation — separate containers for core and database.

Logging — separate logs for host and container.

Multilingual support — language switching via config.json and new languages via lang.json.

Use Cases

Pentests and penetration testing

Infrastructure and web service audits

Go and corporate network security

De and CI/CD

Tech Stack

Python — main de language

PostgreSQL — database

Docker — en containerization

Jinja2 — report templates

Rich — terminal tables

WeasyPrint — PDF generation

Integrated Tools

| Tool | Description | |
|---------|-----------------------------------------------------------------------------|--------------------------|
| nmap | Powerful network scanner for port discovery and service/ detection. | !v |
| nikto | Web ser for detecting misconfigurations and . | !v |
| dig | Command-line DNS lookup utility for querying name servers. | !v |
| nuclei| Fast scanner based on YAML templates. | !v |

Architecture

System Components

1. Plugins (plugins/*.py) — wrapper modules for CLI tools (e.g., nmap, nikto). Each plugin implements the following functions:
- scan() — runs the scanner and saves the path to the result file (.xml, .json);
- parse() — parses the results;
- merge_entries() — merges data by IP and Domain into source: "Both";
- get_column_order() and get_wide_fields() — configure table column order and formatting.
2. Runner (plugin_runner.py) — launches plugins and saves the paths to their results in a temporary JSON (/tmp/temp_files_*.json) without storing the actual file content.
3. Collector (collector.py) — loads file paths, calls parse() / merge_entries(), filters out uninformati, and stores the result in the results table.
4. Database (PostgreSQL) — centralized repository for all results, all data is con to a single schema and stored in tables.
5. Report Generator (report_generator.py) — retrieves data from the database, groups it by category, and it as:
- terminal report,
- HTML,
- PDF.
6. Configuration Module (config/config.json) — defines scanning targets (target_ip, target_domain), acti, scan levels, report formats, theme (light / dark), and behavior (open_report, clear_db, etc.).
7. Startup Wrapper (start.py) — single entry point that orchestrates Docker en setup, database launch, scanner execution, data collection, and report generation with progress indicators.
8. Docker En — isolated and fully self-contained en:
- beescan_base — container with all scanners and logic,
- postgres — separate container for the database,
- beescan_network — bridge network connecting the components.

Project Structure

Pipeplan: How It Works

System Startup

1. The system is started via start.sh. The bash wrapper checks the en, launches start.py, and runs the orchestration pipeline.
2. Docker and the beescan_network network are checked/created.
3. Containers are started:
* PostgreSQL (beescan_postgres)
* beescan-base (core logic + scanners)
4. plugin_runner.py is launched for asynchronous scanning of targets.
5. Paths to scan results are saved in a temporary file /tmp/temp_files_*.json.
6. collector.py is launched to parse, normalize, filter, and write results to the DB (strictly to the snapshot schema).
7. Reports are generated: terminal, html, pdf — all based on DB data via report_generator.py.

Plugin Workflow (plugin_runner.py)

1. Plugin activity is determined via config.json.
2. The scan() function is called asynchronously:
* Launches the scanner (e.g., nmap) with the required profile/arguments.
* Sa (XML, JSON, STDOUT) to temporary files.
3. Temporary files are not read directly; only their paths are saved to a temporary JSON.
4. Only the collector operates with the results from this point.

Data Collection (collector.py)

1. The collector connects to the database.
2. Loads the plugin parser from plugins/*.py.
3. Processes all temporary files (temp_files_*.json):
* Calls parse() to parse results,
* Calls merge_entries() to unify duplicates,
* Filters out non-informati.
4. All valid entries are distributed across tables:
* hosts — unique IPs/FQDNs and OS info.
* services — unique services (port, protocol, CPE, product, etc.).
* vuln — result for each service finding (always includes se, description, references, etc.).
* e — if needed, stores original logs (e.g., XML or stdout).
* registry — dynamic index of targets for passi plugins.

Unified Data Schema

* Any plugin result is always mapped to uni fields: host, service, port, protocol, se, description, e, references, source.
* If a plugin returns something specific, it goes into meta, e, or an extended description field.
* Raw data (e) is optional: e.g., for nmap, original XML/STDOUT can be saved in e; for nuclei — the JSON report, etc.

Report Generation (report_generator.py)

1. Fresh data is extracted from the snapshot: tables hosts, services, vuln, e, registry.
2. Data is automatically grouped by category and acti according to config.json (category for each plugin).
3. For each plugin, the following are queried:
* column order (get_column_order())
* wide fields (get_wide_fields())
* view (get_())
4. Generates reports in the selected formats:
* Terminal report (rich tables, full plugin output)
* HTML report (via the uni Jinja2 template report.html.j2, adapting to each plugin's structure)
* PDF report (generated from HTML )
5. Theme selection is supported ("light" or "dark").
6. All reports are built strictly from the current state of the DB — no intermediate JSON/logs are used.

Nmap Example

1. The nmap module is enabled, a scan profile is set (easy / middle / hard).
2. For each target (ip/domain/network), nmap is run with the respecti (arguments, ports, scripts).
3. Each result is sa, then collected, parsed, and normalized functions (parse(), merge_entries(), get_()).
4. All data is strictly stored in the snapshot:
* services (services)
* hosts (hosts)
* indi findings (vuln)
* if needed, raw XML (e)
5. All results are in the reports:
* Terminal — aggregated output for all services and se levels.
* HTML/PDF — tabular, with sorting, filtering by categories/plugins, scan duration, and theme support.

Installation and Launch

Launching the Project

You will be prompted to select a language during setup.

Configuration

All parameters are set in config.json:

| Parameter | Default value | What true/value does | What false/other value does |
|----------------------|-------------------------|-------------------------------------------------------------|------------------------------------------------|
| target_ip | "1.1.1.1" | Scans the specified IP address | — |
| target_domain | "" | Scans the specified domain | — |
| target_network | "" | Scans the specified network range (e.g., 1.1.1.0/24) | — |
| target_api | "" | For integration with external API (optional) | — |
| report_formats | ["terminal", "html"] | Generates the selected report formats | — |
| open_report | true | Automatically opens HTML/PDF report in browser | Does not open reports in browser |
| clear_logs | true | Clears logs before each run | Logs are accumulated |
| clear_reports | true | Deletes old reports before each run | Old reports are preserved |
| clear_db | true | Clears all database tables before scanning | Old data in the database is preserved |
| report_theme | "dark" | Uses dark theme for HTML and PDF reports | "light" — uses light report theme |
| plugins | see section below | List of acti and their parameters | — |

To-Do

<!--KANBAN_START-->
| Todo (5) | In Progress (1) | Done (28) |
| --- | --- | --- |
| PDF reports | Summary of by se | Expose Raw E and Expandable Details for Each Finding in HTML Report |
| Proxy integration (Tor/Chain) | &nbsp; | Normalize database structure and remo results table |
| Integrate dig | &nbsp; | Nikto: Auto-select web ports from Nmap scan results |
| Integrate nuclei | &nbsp; | Dynamic plugin chaining: automatic orchestration based on scan dependencies |
| Multi-language support (RU/EN) | &nbsp; | Implement target registry for cross-plugin orchestration |
| &nbsp; | &nbsp; | Strict report and plugin order in output (categories + plugins) |
| &nbsp; | &nbsp; | se classification |
| &nbsp; | &nbsp; | Add network target support to nmap plugin configuration |
| &nbsp; | &nbsp; | Add require and enabled fields to Nmap |
| &nbsp; | &nbsp; | Auto-update Kanban board in README from GitHub Projects |

<!--KANBAN_END-->

Donate

USDT (TRC20)/USDC (TRC20): TUQj3sguQjmKFJEMotyb3kER

SOL (Solana): 6KTSq4r4E3N1bsoPaxQgr4

XRP (XRP): rDkEZehHFqSjiGdBHsseR64fCcRXuJbgfr

---

🛡 Licensed for non-commercial use only. See LICENSE for details.

项目信息

开发语言：Python

Star 数：30

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Modular platform for security auditing of networks, web, DNS & APIs. Plugin-based, Docker-isolated, and report-driven.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。