shadowlab - A sandboxed, defensive-only security exercise runn

项目说明

shadowlab

A sandboxed defensi exercise runner. Log-analysis,
config-audit, and incident-response scenarios, each scored with partial
credit and a plain-English explanation for every point earned or lost.
E is local and synthetic -- there is no network call, no exploit
code, and no destructi anywhere in this repository. This is a
teaching lab for the blue team, not a red-team tool.

Why

Most "SOC training" content is either a paid platform behind a login wall,
or a CTF that rewards exploitation. shadowlab is neither: it's a pip
install-able local grader you can point at synthetic fixtures, get honest
partial credit, and see *why* you lost points -- the same way a real
findings report reads. Every scenario's "ground truth" is the
output of a real detection algorithm or a genuinely reasoned incident
response playbook, not a hardcoded answer key -- see
CONTRIBUTING.md for how new scenarios are held to that
bar.

Quickstart

What it looks like

shadowlab list:

shadowlab submit brute_force_ssh --answers answers.json -- a near-miss
submission (wrong breach timestamp by 13 seconds, half the username list)
graded with partial credit and an explanation per rubric item:

shadowlab report --out report.html renders every recorded attempt into a
dark-themed, self-contained HTML report card with a per-rubric-item
breakdown -- open it in a browser, or attach it to a training write-up.

The 7 bundled scenarios

| id | category | what you're finding |
|---|---|---|
| brute_force_ssh | log-analysis | An attacker credential-stuffs sshd from one IP and finally breaks in. Find the IP, the breached account, the breach timestamp, and every username tried. |
| web_scanner_probe | log-analysis | An automated scanner (SQLi + path tra + a known tool user-agent) sweeps an nginx-style access log and uploads a webshell. |
| exfil_flow_logs | log-analysis | Buried in ordinary DNS/HTTPS chatter, one workstation moves ~780MB to a single external IP over a non-standard port -- classic exfiltration shape. |
| firewall_audit | config-audit | Review an iptables-save capture and pick out the real exposure risks (telnet open, a backdoor-shaped port, RDP open to the world) without flagging the fine stuff. |
| sshd_hardening | config-audit | Review a captured sshd_config for real hardening gaps (root login, empty passwords, weak ciphers/MACs) without flagging settings that are already correct. |
| ransomware_ir | incident-response | A file server gets encrypted after a phished workstation RDPs in with a shared service account. Submit an ordered response plan; harmful/wrong actions (paying the ransom, reconnecting early) cost you points. |
| phishing_bec_ir | incident-response | A spoofed-CFO wire-fraud email is caught before money moves, but the real mailbox is compromised with a malicious forwarding rule. Submit an ordered containment-through-lessons-learned plan. |

Run shadowlab show <id> for the full prompt, the bundled fixture, and the
exact submission schema (which fields to submit, or which catalog ids are
a to choose from).

Architecture

The key design choice: a scenario's "ground truth" is never a hand-typed
answer key sitting next to the fixture. For log-analysis and config-audit
scenarios it is the li of a real detector/auditor function run
against the bundled fixture at grading time -- the same function is
golden-file tested against that fixture in tests/, so fixture and
detector can ne drift apart. For incident-response scenarios,
"ground truth" is a hand-authored but explicitly-documented ideal action
sequence plus a set of clearly-labeled harmful distractors.

Scoring rubric

Every scenario is scored out of 100 points with three separate rubric
strategies, chosen per scenario kind:

Weighted field comparison (log-analysis): each expected field (an

IP, a timestamp, a byte count, a set of usernames) carries a weight and a
comparator -- exact match, numeric tolerance with linear decay, or set
o (Jaccard) for list fields. Every field reports the ratio earned
and why.

Se checklist (config-audit): each real finding is

worth points proportional to its se (info through critical);
flagging something that *isn't* a real finding costs a flat penalty, so
submitting every possible id is not a winning strategy.

Ordered-action scoring (incident-response): three independently

reported components -- how many correct actions you included
(co), whether you did them in the right relati (Preparation
-> Identification -> Containment -> Eradication -> Recovery -> Lessons
Learned), and whether you a the harmful/wrong distractors mixed
into the catalog.

De

CI (.github/workflows/ci.yml) runs all three across Python 3.11-3.13 on
Linux, Windows, and macOS, plus a CLI smoke test that submits a real
answer and asserts the exported HTML report contains it.

See CONTRIBUTING.md for the checklist to follow when
adding a new scenario, and CHANGELOG.md for release notes.

Safety

Every log line, config file, and incident brief in this repository is
synthetic, in for this project. No fixture was copied from a real
breach, a real customer en, or real personal data. No code path in
src/shadowlab performs a network call, executes a payload, or otherwise
acts on a real target -- the entire tool reads bundled text files and
writes local JSON/HTML. If you're looking for offensi, this
isn't it, by design.

License

MIT (c) 2026 Prabesh Sharma -- see LICENSE.

项目信息

开发语言：Python

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A sandboxed, defensive-only security exercise runner: log-analysis, config-audit, and incident-response scenarios with scored partial credit.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

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

使用与学习建议

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

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

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

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

免责声明

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