kveldulf1/security-log-analysis-tool
GitHub: kveldulf1/security-log-analysis-tool
一款 CLI + TUI 安全日志分析工具，通过可配置检测规则和跨来源 IP 关联，从 Apache access log 与 syslog auth.log 中发现多向量攻击行为。
Stars: 0 | Forks: 0
# security-log-analysis-tool
[](https://github.com/kveldulf1/security-log-analysis-tool/actions/workflows/ci.yml)
[](https://github.com/kveldulf1/security-log-analysis-tool/security/code-scanning)
[](https://www.python.org/)
这是一款 CLI + TUI 工具，用于解析 Apache 风格的 access log 和 syslog `auth.log` 文件，
检测可疑活动（暴力破解、路径遍历、SQLi 探测、扫描器
爆发、速率限制滥用、敏感 `sudo` 命令、SSH 用户枚举），并且
**通过 IP 将来自这两个来源的发现进行关联**，从而揭示单一日志视图
容易遗漏的多向量攻击。本项目作为一项 48 小时的招聘评估测试进行开发，包含具有生产级特征的附加功能：基于角色的权限控制、用于并发分析的作业队列、
Textual TUI、JSON/CSV/SARIF 导出、电子邮件 + 桌面通知提醒、Allure
HTML 回归报告，以及 GitHub Actions / Jenkins pipeline。
## 目录
- [功能](#features)
- [架构](#architecture)
- [安装说明](#install)
- [快速开始](#quickstart)
- [CLI 用法](#cli-usage)
- [TUI 用法](#tui-usage)
- [配置](#configuration)
- [测试与回归套件](#testing--regression-suite)
- [Docker](#docker)
- [CI/CD](#cicd)
- [性能与扩展性](#performance--scaling)
- [安全说明](#security-notes)
- [项目布局](#project-layout)
- [AI 辅助开发](#ai-assisted-development)
## 功能
- **双解析器，单一 pipeline** — Apache combined log 和 syslog `auth.log`，
按文件自动检测，并标准化为通用的 `LogEvent`（支持 UTC
时间戳）。格式错误的行会被计数并记录为 WARNING，绝不会导致运行崩溃。
- **可配置的检测规则** (`config/rules.yaml`) — 暴力破解 (web +
SSH)、暴力破解后成功提权、路径遍历 (原始 + URL 解码)、
SQL 注入 探测、扫描器爆发、速率限制滥用、敏感 `sudo`
命令、SSH 无效用户枚举、失败后快速成功。每个
正则表达式都经过了锚定和 ReDoS 审查。
- **跨来源关联** — 同一 IP 在
一个时间窗口内，在 ≥2 个日志来源中触发 ≥2 条不同规则，将升级为由关联子发现组成的 `CRITICAL` 级别发现。
- **退出码约定**（CI 友好）：`analyze` 返回 `0` = 干净无威胁，
`1` = 至少有一个 HIGH/CRITICAL 发现，`2` = 配置/使用错误。
- **导出**：JSON、CSV 和 SARIF 2.1.0（经过 schema 验证，使用相对于仓库的
URI）— SARIF 可直接输入到 GitHub 的 Security → Code scanning 标签页。
- **基于角色的权限控制** (`analyst` / `admin`) 在服务层强制执行，
scrypt 密码哈希，SQLite 用户存储，5 次失败/锁定 15 分钟机制。
- **并发** — 一个有界的进程内作业队列 + worker 池，用于同时
运行多个分析任务，具有明确的背压机制（不会静默丢弃任务）。
- **Watch 模式** — 持续追踪实时日志文件，随着新
行的到达进行增量分析。
- **Textual TUI** — 登录、启动/停止分析、浏览发现、追踪工具
日志并支持实时级别过滤；无效输入绝不会导致程序退出。
- **告警** — 作业中严重程度超过配置阈值的发现将触发
电子邮件 (SMTP/STARTTLS) 和 Windows 桌面通知；失败的 sink
绝不会导致分析任务失败。
- **质量工程**：pytest 单元/端到端/性能/OWASP 测试套件，Gherkin/behave
BDD 回归测试套件，合并两者的 Allure HTML 报告，GitHub Actions
(冒烟测试 + SARIF 上传 + Pages 报告) 和 Jenkins pipeline (完整
回归测试，如果测试套件变红（失败）则构建失败)，以及 Dockerfile。
## 架构
```
flowchart LR
subgraph Input
A[access.log]
B[auth.log]
end
subgraph Pipeline
P1[Apache parser]
P2[Syslog parser]
E[AnalysisEngine]
D[Detection rules
config/rules.yaml] C[Correlation engine] end subgraph Output R[Rich console report] X[JSON / CSV / SARIF export] AL[AlertDispatcher
email + toast] end subgraph Interfaces CLI[analyze / watch / users CLI] TUI[Textual TUI] Q[JobQueue + WorkerPool] end A --> P1 --> E B --> P2 --> E E --> D --> C --> R C --> X C --> AL CLI --> E TUI --> Q --> E ``` `pipeline/engine.py` 将事件流式传输通过配置的规则和 关联引擎；对于大文件，不会将任何内容完全物化到内存中。 作业队列 (`pipeline/queue.py`) 是一个接口，而不是硬性依赖项 — 请参阅 [性能与扩展性](#performance--scaling) 了解在生产环境中如何将其替换为 分布式 broker。 ## 安装说明 全新机器上的前置条件，按功能区域分类： | 需求 | 要求 | 安装 | |---|---|---| | 运行此工具 | Python 3.11+ | [python.org](https://www.python.org/downloads/) 或使用您的操作系统包管理器 | | 容器构建/运行 | Docker Desktop (或 Docker Engine) | [docker.com](https://www.docker.com/products/docker-desktop/) | | 本地 Allure HTML 报告 | Java JRE/JDK | 任何 JDK 11+；通过 `scoop install allure` 或 `npm i -g allure-commandline` 安装 CLI | | 本地 Jenkins pipeline | JDK + Jenkins (原生或 [Docker](https://www.jenkins.io/doc/book/installing/docker/)) + Allure Jenkins 插件 | [jenkins.io](https://www.jenkins.io/download/) | 克隆并安装（可编辑模式，包含开发/测试扩展）： ``` git clone https://github.com/kveldulf1/security-log-analysis-tool.git cd security-log-analysis-tool python -m pip install -e ".[dev]" pre-commit install # activates the ruff pre-commit hook ``` 建议使用虚拟环境，但非强制要求： ``` python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate python -m pip install -e ".[dev]" ``` ## 快速开始 ``` security-log-analysis-tool --version # 分析已提交的示例日志 — exits 1，显示两个展示用关联 security-log-analysis-tool analyze sample_logs/access.log sample_logs/auth.log # 干净且仅含良性活动的日志 exits 0，零发现 security-log-analysis-tool analyze sample_logs/clean_access.log ``` ## CLI 用法 ``` security-log-analysis-tool analyze FILES... [--rules PATH] [--format auto|apache|syslog] [--export json|csv|sarif] [--output PATH] [--no-alerts] [--min-severity low|medium|high|critical] ``` - `--rules` — 规则 YAML 的路径（默认为 `config/rules.yaml`）； 无效文件（错误的 YAML、未知的规则类型、错误的正则表达式）将以 `2` 退出，并附带可操作的 错误信息，绝不会显示 traceback。 - `--format` — 强制使用特定解析器，而不是按文件自动检测。 - `--export/--output` — 将发现写入 JSON、CSV 或 SARIF 2.1.0。 - `--no-alerts` — 跳过本次运行的电子邮件/toast 告警分发。 - `--min-severity` — 同时过滤控制台报告和任何导出内容。 退出码：`0` 没有 HIGH+ 发现 · `1` 至少有一个 HIGH/CRITICAL 发现 · `2` 配置或使用错误。 ``` # 为 GitHub code scanning 导出 SARIF（参见 .github/workflows/ci.yml） security-log-analysis-tool analyze sample_logs/access.log sample_logs/auth.log \ --export sarif --output findings.sarif --no-alerts ``` 随着项目的发展，附加的子命令会通过自动发现的 `commands/` 注册表加入（添加新命令时 `cli.py` 永远不需要修改）：`watch FILES...` （持续追踪，增量分析）、`tui`（见下文）以及 `users add|list|remove|seed-demo`（基于角色的账户管理）。运行 `security-log-analysis-tool --help` 以查看您检出的代码中可用的确切命令集。 ## TUI 用法 ``` security-log-analysis-tool tui ``` 登录（基于角色：`analyst` / `admin`） → 主菜单：启动分析、停止 正在运行/排队中的作业、浏览发现（按严重程度着色的表格）、查看工具 日志（提示输入日志级别并实时过滤）、注销或退出（优雅地排空 作业队列 — 不会泄漏线程）。每个屏幕都会验证输入； 无效输入绝不会导致程序退出，而是重新提示或返回到 主菜单。下方的演示账户**仅**存在于测试/文档中，绝不会出现在 应用程序日志或已提交的数据中： | 用户名 | 密码 | 角色 | |---|---|---| | `amelia.reyes` | `Password123!` | admin | | `oscar.lindqvist` | `P@ssword123?` | analyst | 使用 `security-log-analysis-tool users seed-demo` 在本地播种这些账户。 ## 配置 **`config/rules.yaml`** — `version`、`defaults.window_seconds`、 `alerts.{min_severity, sinks}`，以及一个 `rules[]` 列表（包含 `id`、`type`、`enabled`、 `severity`、`source`，加上特定于类型的调节参数，如 `threshold`、 `window_seconds`、`statuses`、`patterns`）。未知的规则类型在 加载时会抛出明显的错误并列出有效类型；正则表达式按照约定进行了锚定，并且 没有嵌套量词（ReDoS 审查 — 请参阅 [安全说明](#security-notes)）；过长的行（>8 KB）会被预先截断。 **`.env`**（从 `.env.example` 复制，已被 gitignored — 切勿提交） — CLI 身份验证回退 (`SLAT_USERNAME`/`SLAT_PASSWORD`)、SMTP 告警凭据以及 日志级别。`.env.example` 仅附带占位符。 ## 测试与回归套件 ``` python -m pytest -m smoke -q # fast subset (~15 checks), what CI runs on every push python -m pytest -q # full unit + e2e + perf + OWASP suite python -m pytest -q -m "not perf" # skip the concurrency/throughput perf suite behave --tags=@smoke features # BDD smoke slice behave features # full Gherkin regression suite ``` 标记：`smoke`（快速测试，每次推送时运行）、`regression`（行为测试）、 `e2e` (CLI 子进程 / TUI Pilot)、`perf` (并发/吞吐量，作业规模测试)、 `owasp` (OWASP Top 10 映射测试)。每次错误修复都会附带一个回归测试。 **Allure HTML 报告**（本地需要 JDK — CI 环境从不需要）： ``` python -m pytest -q --alluredir=allure-results behave -f allure_behave.formatter:AllureFormatter -o allure-results features allure generate allure-results -o allure-report --clean allure open allure-report # or open allure-report/index.html directly ``` 两个运行程序都写入同一个 `allure-results` 目录，因此 生成的报告将被读取为一份合并后的回归文档（单元测试 + BDD）。 ## Docker ``` docker build -t slat . # Windows PowerShell — 以只读方式挂载已提交的示例日志 docker run --rm -v "${PWD}\sample_logs:/logs:ro" slat analyze /logs/access.log /logs/auth.log # exits 1，发现结果输出到 stdout docker run --rm -v "${PWD}\sample_logs:/logs:ro" slat analyze /logs/clean_access.log # exits 0，零发现 docker run --rm slat --help # exits 0 ``` 该镜像基于 `python:3.12-slim`，为单阶段构建（纯 Python — 构建阶段之间 没有需要丢弃的东西），并以非 root 用户 `appuser` 运行。没有 `HEALTHCHECK`：这是一个短暂的 CLI 调用，而不是长期运行的 服务。 ## CI/CD **GitHub Actions** (`.github/workflows/ci.yml`)，包含三个作业： - `test` — 在每次推送/PR 时执行：安装，`ruff check`/`ruff format --check`， `pytest -m smoke`，`behave --tags=@smoke`，两者输出到同一个 `allure-results` 目录，并作为 artifact 上传。 - `allure-pages` — 在 `master` 分支上且 `test` 成功后执行：渲染合并后的 Allure 报告并将其发布到 GitHub Pages（在 多次运行中保留历史/趋势记录）。 - `sarif` — 分析提交的 `sample_logs/` 并将 SARIF 输出上传到 **Security → Code scanning** (`security-events: write`)；这里 `analyze` 的退出代码 `1` 是*预期*的结果（存在发现）， 而不是工作流失败。 **Jenkins** (`Jenkinsfile`，原生 Windows agent — 请参阅 [docs/manual-tests.md](docs/manual-tests.md) 了解一次性作业设置)： 每 5 分钟轮询一次 SCM（本地 Jenkins 没有用于 webhook 的公共 URL）， 设置一个全新的 venv，然后运行**完整的** `pytest` + `behave` 回归 测试套件 — 任何失败都会导致构建失败（变红），这是设计使然：一个不能阻止合并的回归测试套件就没有发挥它的作用。`post { always { allure ... } }` 无论结果如何，都会通过 Allure Jenkins 插件发布 Allure 报告。 ## 性能与扩展性 20 个并发作业的性能测试、吞吐量/内存限制测试、背压 测试以及 watch 模式的持续摄取测试被特意限定在 **作业规模**（见 `tests/perf/`），而不是生产基准测试。 生产环境的扩展性体现在架构上，而不是在本地盲目追求数字的提升： - `JobQueue`/`WorkerPool` 定义在一个小型接口背后 — 替换为 分布式 broker (Redis, SQS) 并提高 worker 数量，无需 修改调用方的代码。 - 高频解析器（极大量数据摄取）可以替换为 基于相同 `Parser` protocol 的 Rust/Go 实现。 - 一旦单进程的 worker 池成为瓶颈，按文件/来源进行分片就是自然的下一步。 ## 安全说明 - **脱敏是一个关键控制点，而不是按次调用决定**：在 任何内容到达 `app.log`/`app.jsonl`、控制台报告 或任何导出格式之前，`redaction.py` 会清除机密/PII（密码、token、API 密钥、私钥块、 电子邮件） — 包括像 SSH 用户名这样由攻击者控制的字段。 - **不可信输入**：每一行日志都被视为恶意的 — 正则表达式已 锚定并经过 ReDoS 审查（无嵌套量词），过长的 行被预先截断，格式错误/对抗性的行会被计数并 记录为 WARNING，而不是导致运行。 - **身份验证**：scrypt 密码哈希 (`n=2^15, r=8, p=1`，32 字节 salt) + `hmac.compare_digest`；SQLite 用户存储，100% 参数化查询； 角色检查在服务层强制执行（TUI 只会*隐藏*它 未授予的权限选项）；5 次失败/锁定 15 分钟。 - **机密信息管理**：`.gitignore`/`.claudeignore` 都包含机密的 最低底线（`.env`、`*.pem`、`*.key`、`secrets/` 等）；`.env.example` 仅附带 占位符；此 README 中的演示账户密码仅存在于 测试/文档中，绝不会出现在应用程序状态中。 - OWASP Top 10 行项目通过正面**和**反面测试进行了验证：A01 访问控制（完整的角色 × 权限矩阵）、A02 加密故障、A03 注入 (SQLi 形式的登录，日志内容注入)、A05 配置错误 （审查安全默认值）、A07 身份验证失败（锁定，弱密码 拒绝）、A09 日志记录失败（机密信息永远不会到达日志）。 ## 项目布局 ``` src/security_log_analysis_tool/ cli.py # auto-discovering command dispatcher commands/ # one module per subcommand (analyze, watch, users, tui) parsers/ # apache_access.py, syslog_auth.py, registry detection/ # one rule module per detector + registry correlation/ # cross-source escalation engine pipeline/ # engine.py (streaming), queue.py, watch.py export/ # json_export.py, csv_export.py, sarif_export.py report/console.py # Rich console rendering auth/ # passwords, SQLite store, service, authz alerts/ # email + toast sinks, dispatcher tui/ # Textual app + screens config/rules.yaml # default detection rules sample_logs/ # committed fixtures (showcase + clean + adversarial) tests/{unit,e2e,perf,fixtures}/ features/ # Gherkin BDD regression suite (behave) docs/manual-tests.md # procedures that need a human (SMTP, Jenkins UI, ...) ``` ## AI 辅助开发 本项目是通过 Claude Code 在一系列有明确范围的会话中构建的； 每个会话的逐字对话历史记录已作为提交的一部分保存在 [`session-logs/`](session-logs/) 下。
config/rules.yaml] C[Correlation engine] end subgraph Output R[Rich console report] X[JSON / CSV / SARIF export] AL[AlertDispatcher
email + toast] end subgraph Interfaces CLI[analyze / watch / users CLI] TUI[Textual TUI] Q[JobQueue + WorkerPool] end A --> P1 --> E B --> P2 --> E E --> D --> C --> R C --> X C --> AL CLI --> E TUI --> Q --> E ``` `pipeline/engine.py` 将事件流式传输通过配置的规则和 关联引擎；对于大文件，不会将任何内容完全物化到内存中。 作业队列 (`pipeline/queue.py`) 是一个接口，而不是硬性依赖项 — 请参阅 [性能与扩展性](#performance--scaling) 了解在生产环境中如何将其替换为 分布式 broker。 ## 安装说明 全新机器上的前置条件，按功能区域分类： | 需求 | 要求 | 安装 | |---|---|---| | 运行此工具 | Python 3.11+ | [python.org](https://www.python.org/downloads/) 或使用您的操作系统包管理器 | | 容器构建/运行 | Docker Desktop (或 Docker Engine) | [docker.com](https://www.docker.com/products/docker-desktop/) | | 本地 Allure HTML 报告 | Java JRE/JDK | 任何 JDK 11+；通过 `scoop install allure` 或 `npm i -g allure-commandline` 安装 CLI | | 本地 Jenkins pipeline | JDK + Jenkins (原生或 [Docker](https://www.jenkins.io/doc/book/installing/docker/)) + Allure Jenkins 插件 | [jenkins.io](https://www.jenkins.io/download/) | 克隆并安装（可编辑模式，包含开发/测试扩展）： ``` git clone https://github.com/kveldulf1/security-log-analysis-tool.git cd security-log-analysis-tool python -m pip install -e ".[dev]" pre-commit install # activates the ruff pre-commit hook ``` 建议使用虚拟环境，但非强制要求： ``` python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate python -m pip install -e ".[dev]" ``` ## 快速开始 ``` security-log-analysis-tool --version # 分析已提交的示例日志 — exits 1，显示两个展示用关联 security-log-analysis-tool analyze sample_logs/access.log sample_logs/auth.log # 干净且仅含良性活动的日志 exits 0，零发现 security-log-analysis-tool analyze sample_logs/clean_access.log ``` ## CLI 用法 ``` security-log-analysis-tool analyze FILES... [--rules PATH] [--format auto|apache|syslog] [--export json|csv|sarif] [--output PATH] [--no-alerts] [--min-severity low|medium|high|critical] ``` - `--rules` — 规则 YAML 的路径（默认为 `config/rules.yaml`）； 无效文件（错误的 YAML、未知的规则类型、错误的正则表达式）将以 `2` 退出，并附带可操作的 错误信息，绝不会显示 traceback。 - `--format` — 强制使用特定解析器，而不是按文件自动检测。 - `--export/--output` — 将发现写入 JSON、CSV 或 SARIF 2.1.0。 - `--no-alerts` — 跳过本次运行的电子邮件/toast 告警分发。 - `--min-severity` — 同时过滤控制台报告和任何导出内容。 退出码：`0` 没有 HIGH+ 发现 · `1` 至少有一个 HIGH/CRITICAL 发现 · `2` 配置或使用错误。 ``` # 为 GitHub code scanning 导出 SARIF（参见 .github/workflows/ci.yml） security-log-analysis-tool analyze sample_logs/access.log sample_logs/auth.log \ --export sarif --output findings.sarif --no-alerts ``` 随着项目的发展，附加的子命令会通过自动发现的 `commands/` 注册表加入（添加新命令时 `cli.py` 永远不需要修改）：`watch FILES...` （持续追踪，增量分析）、`tui`（见下文）以及 `users add|list|remove|seed-demo`（基于角色的账户管理）。运行 `security-log-analysis-tool --help` 以查看您检出的代码中可用的确切命令集。 ## TUI 用法 ``` security-log-analysis-tool tui ``` 登录（基于角色：`analyst` / `admin`） → 主菜单：启动分析、停止 正在运行/排队中的作业、浏览发现（按严重程度着色的表格）、查看工具 日志（提示输入日志级别并实时过滤）、注销或退出（优雅地排空 作业队列 — 不会泄漏线程）。每个屏幕都会验证输入； 无效输入绝不会导致程序退出，而是重新提示或返回到 主菜单。下方的演示账户**仅**存在于测试/文档中，绝不会出现在 应用程序日志或已提交的数据中： | 用户名 | 密码 | 角色 | |---|---|---| | `amelia.reyes` | `Password123!` | admin | | `oscar.lindqvist` | `P@ssword123?` | analyst | 使用 `security-log-analysis-tool users seed-demo` 在本地播种这些账户。 ## 配置 **`config/rules.yaml`** — `version`、`defaults.window_seconds`、 `alerts.{min_severity, sinks}`，以及一个 `rules[]` 列表（包含 `id`、`type`、`enabled`、 `severity`、`source`，加上特定于类型的调节参数，如 `threshold`、 `window_seconds`、`statuses`、`patterns`）。未知的规则类型在 加载时会抛出明显的错误并列出有效类型；正则表达式按照约定进行了锚定，并且 没有嵌套量词（ReDoS 审查 — 请参阅 [安全说明](#security-notes)）；过长的行（>8 KB）会被预先截断。 **`.env`**（从 `.env.example` 复制，已被 gitignored — 切勿提交） — CLI 身份验证回退 (`SLAT_USERNAME`/`SLAT_PASSWORD`)、SMTP 告警凭据以及 日志级别。`.env.example` 仅附带占位符。 ## 测试与回归套件 ``` python -m pytest -m smoke -q # fast subset (~15 checks), what CI runs on every push python -m pytest -q # full unit + e2e + perf + OWASP suite python -m pytest -q -m "not perf" # skip the concurrency/throughput perf suite behave --tags=@smoke features # BDD smoke slice behave features # full Gherkin regression suite ``` 标记：`smoke`（快速测试，每次推送时运行）、`regression`（行为测试）、 `e2e` (CLI 子进程 / TUI Pilot)、`perf` (并发/吞吐量，作业规模测试)、 `owasp` (OWASP Top 10 映射测试)。每次错误修复都会附带一个回归测试。 **Allure HTML 报告**（本地需要 JDK — CI 环境从不需要）： ``` python -m pytest -q --alluredir=allure-results behave -f allure_behave.formatter:AllureFormatter -o allure-results features allure generate allure-results -o allure-report --clean allure open allure-report # or open allure-report/index.html directly ``` 两个运行程序都写入同一个 `allure-results` 目录，因此 生成的报告将被读取为一份合并后的回归文档（单元测试 + BDD）。 ## Docker ``` docker build -t slat . # Windows PowerShell — 以只读方式挂载已提交的示例日志 docker run --rm -v "${PWD}\sample_logs:/logs:ro" slat analyze /logs/access.log /logs/auth.log # exits 1，发现结果输出到 stdout docker run --rm -v "${PWD}\sample_logs:/logs:ro" slat analyze /logs/clean_access.log # exits 0，零发现 docker run --rm slat --help # exits 0 ``` 该镜像基于 `python:3.12-slim`，为单阶段构建（纯 Python — 构建阶段之间 没有需要丢弃的东西），并以非 root 用户 `appuser` 运行。没有 `HEALTHCHECK`：这是一个短暂的 CLI 调用，而不是长期运行的 服务。 ## CI/CD **GitHub Actions** (`.github/workflows/ci.yml`)，包含三个作业： - `test` — 在每次推送/PR 时执行：安装，`ruff check`/`ruff format --check`， `pytest -m smoke`，`behave --tags=@smoke`，两者输出到同一个 `allure-results` 目录，并作为 artifact 上传。 - `allure-pages` — 在 `master` 分支上且 `test` 成功后执行：渲染合并后的 Allure 报告并将其发布到 GitHub Pages（在 多次运行中保留历史/趋势记录）。 - `sarif` — 分析提交的 `sample_logs/` 并将 SARIF 输出上传到 **Security → Code scanning** (`security-events: write`)；这里 `analyze` 的退出代码 `1` 是*预期*的结果（存在发现）， 而不是工作流失败。 **Jenkins** (`Jenkinsfile`，原生 Windows agent — 请参阅 [docs/manual-tests.md](docs/manual-tests.md) 了解一次性作业设置)： 每 5 分钟轮询一次 SCM（本地 Jenkins 没有用于 webhook 的公共 URL）， 设置一个全新的 venv，然后运行**完整的** `pytest` + `behave` 回归 测试套件 — 任何失败都会导致构建失败（变红），这是设计使然：一个不能阻止合并的回归测试套件就没有发挥它的作用。`post { always { allure ... } }` 无论结果如何，都会通过 Allure Jenkins 插件发布 Allure 报告。 ## 性能与扩展性 20 个并发作业的性能测试、吞吐量/内存限制测试、背压 测试以及 watch 模式的持续摄取测试被特意限定在 **作业规模**（见 `tests/perf/`），而不是生产基准测试。 生产环境的扩展性体现在架构上，而不是在本地盲目追求数字的提升： - `JobQueue`/`WorkerPool` 定义在一个小型接口背后 — 替换为 分布式 broker (Redis, SQS) 并提高 worker 数量，无需 修改调用方的代码。 - 高频解析器（极大量数据摄取）可以替换为 基于相同 `Parser` protocol 的 Rust/Go 实现。 - 一旦单进程的 worker 池成为瓶颈，按文件/来源进行分片就是自然的下一步。 ## 安全说明 - **脱敏是一个关键控制点，而不是按次调用决定**：在 任何内容到达 `app.log`/`app.jsonl`、控制台报告 或任何导出格式之前，`redaction.py` 会清除机密/PII（密码、token、API 密钥、私钥块、 电子邮件） — 包括像 SSH 用户名这样由攻击者控制的字段。 - **不可信输入**：每一行日志都被视为恶意的 — 正则表达式已 锚定并经过 ReDoS 审查（无嵌套量词），过长的 行被预先截断，格式错误/对抗性的行会被计数并 记录为 WARNING，而不是导致运行。 - **身份验证**：scrypt 密码哈希 (`n=2^15, r=8, p=1`，32 字节 salt) + `hmac.compare_digest`；SQLite 用户存储，100% 参数化查询； 角色检查在服务层强制执行（TUI 只会*隐藏*它 未授予的权限选项）；5 次失败/锁定 15 分钟。 - **机密信息管理**：`.gitignore`/`.claudeignore` 都包含机密的 最低底线（`.env`、`*.pem`、`*.key`、`secrets/` 等）；`.env.example` 仅附带 占位符；此 README 中的演示账户密码仅存在于 测试/文档中，绝不会出现在应用程序状态中。 - OWASP Top 10 行项目通过正面**和**反面测试进行了验证：A01 访问控制（完整的角色 × 权限矩阵）、A02 加密故障、A03 注入 (SQLi 形式的登录，日志内容注入)、A05 配置错误 （审查安全默认值）、A07 身份验证失败（锁定，弱密码 拒绝）、A09 日志记录失败（机密信息永远不会到达日志）。 ## 项目布局 ``` src/security_log_analysis_tool/ cli.py # auto-discovering command dispatcher commands/ # one module per subcommand (analyze, watch, users, tui) parsers/ # apache_access.py, syslog_auth.py, registry detection/ # one rule module per detector + registry correlation/ # cross-source escalation engine pipeline/ # engine.py (streaming), queue.py, watch.py export/ # json_export.py, csv_export.py, sarif_export.py report/console.py # Rich console rendering auth/ # passwords, SQLite store, service, authz alerts/ # email + toast sinks, dispatcher tui/ # Textual app + screens config/rules.yaml # default detection rules sample_logs/ # committed fixtures (showcase + clean + adversarial) tests/{unit,e2e,perf,fixtures}/ features/ # Gherkin BDD regression suite (behave) docs/manual-tests.md # procedures that need a human (SMTP, Jenkins UI, ...) ``` ## AI 辅助开发 本项目是通过 Claude Code 在一系列有明确范围的会话中构建的； 每个会话的逐字对话历史记录已作为提交的一部分保存在 [`session-logs/`](session-logs/) 下。
标签：CISA项目, LNA, Python, SARIF, TUI, 安全规则引擎, 无后门, 请求拦截, 逆向工具