Baylox/sentinel-py
GitHub: Baylox/sentinel-py
SentinelPy 是一个轻量级模块化的 Python 漏洞扫描器，提供端口扫描、SSL 证书分析和 HTTP 标头检查，适用于安全学习与内部审计。
Stars: 3 | Forks: 0
# SentinelPy
SentinelPy 是一个用 Python 构建的轻量级、模块化漏洞扫描器。它可以执行本地安全检查，例如端口扫描、SSL 证书分析和 HTTP 标头检查。专为学习、审计和内部测试而设计。
## 安装说明
### 从 PyPI 安装（即将推出）
```
pip install sentinelpy
```
### 从源码安装
1. 克隆仓库：
git clone https://github.com/Baylox/sentinel-py.git
cd sentinel-py
2. 以可编辑模式安装并包含开发依赖：
pip install -e ".[dev]"
或者不包含开发工具：
pip install -e .
## 使用说明
### 基础扫描
```
sentinelpy example.com 20-80
```
### 多模块扫描
```
sentinelpy example.com 20-443 --modules tcp http ssl
```
### SSL 证书检查
```
sentinelpy google.com 443-443 --modules ssl
```
### 导出结果
```
sentinelpy example.com 20-80 --json results.json
```
### 并发扫描
TCP 扫描器会并发连接端口，因此每个端口的连接
超时时间是重叠的，而不是依次运行。这使得大型扫描
（以及对被过滤/无响应主机的扫描）速度大幅提升。使用 `--workers` 调整并发连接数（默认：100，范围：1–1000）：
```
# Fast scan of a large range
sentinelpy example.com 1-1000 --workers 200
# Single-threaded scan (sequential)
sentinelpy example.com 1-1000 --workers 1
```
### 旧版用法（直接使用 Python）
```
python main.py example.com 20-80
```
## 速率限制
SentinelPy 包含内置的速率限制，以防止目标过载并降低扫描的可检测性。这对于**合规的扫描**至关重要，并有助于避免无意中的拒绝服务攻击。
### 预设
| 预设 | 延迟 | 请求/秒 | 使用场景 |
| --------------------- | --------------- | ------------ | ---------------------------------------- |
| `--preset stealth` | ~1s（带抖动） | ~1 req/s | 隐蔽扫描，模拟人类行为 |
| `--preset normal` | 50ms | ~20 req/s | **默认**，兼顾速度与隐蔽性 |
| `--preset aggressive` | 10ms | ~100 req/s | 内部网络上的快速扫描 |
| `--preset none` | 无延迟 | 无限制 | 仅限本地测试，**不推荐** |
### 示例
```
# Default scan (normal preset: 50ms delay, ~20 req/s)
sentinelpy example.com 1-1000
# Stealth scan for external targets
sentinelpy example.com 1-1000 --preset stealth
# Fast scan for internal networks
sentinelpy 192.168.1.1 1-1000 --preset aggressive
# Custom delay (5 requests per second)
sentinelpy example.com 1-100 --delay 0.2
# Disable rate limiting (use responsibly)
sentinelpy localhost 1-1000 --preset none
```
查看所有选项：
```
sentinelpy --help
```
## 开发说明
### 配置开发环境
```
# Create virtual environment
python -m venv .venv
# Activate (Windows)
.\.venv\Scripts\Activate
# Activate (Linux/Mac)
source .venv/bin/activate
# Install with dev dependencies
pip install -e ".[dev]"
# Install the pre-commit hooks (runs black, isort & flake8 on each commit)
pre-commit install
```
### 代码质量
```
# Format code
black scanner/ tests/
isort scanner/ tests/
# Lint
flake8 scanner/ tests/
# Type-check
mypy scanner/
# Run tests
pytest
# With coverage
pytest --cov=scanner --cov-report=html
# Security scan (static analysis + dependency audit)
bandit -r scanner/
pip-audit
# Run all pre-commit hooks against the whole repo
pre-commit run --all-files
```
`makefile` 封装了这些命令（`make test`、`make lint`、`make typecheck`、
`make check`、`make coverage`、`make security`）。如有需要，可以使用
`make PY=python3` 覆盖解释器。
### 持续集成
每次推送和拉取请求都会运行 [CI 工作流](./.github/workflows/ci.yml)：
涵盖 Python 3.8–3.13 的测试，以及 lint、类型检查和安全作业。
### 架构
阅读[架构文档](./docs/ARCHITECTURE.md)以了解本项目所使用的设计模式（Services、DTOs、Registry）。
## 项目路线图
[路线图](./docs/ROADMAP.md)概述了即将推出的功能、里程碑和未来的改进。
## 免责声明
本工具仅供**教育和授权的安全测试目的**使用。
您对**合规且合法地**使用本工具负全部责任。
**请勿**将其用于您不拥有或未获得明确测试许可的系统。
尽管本项目基于 MIT 许可证，但作者对代码的任何滥用或非法应用**不承担任何责任**。
标签：DNS枚举, Python, 加密, 安全规则引擎, 密码管理, 并发扫描, 插件系统, 数据统计, 无后门, 漏洞扫描器, 端口扫描, 网络安全工具, 逆向工具