Linux Server Security Intrusion Detection & Forensics Tool | Linux Server Security Intrusion Detection & Forensics Tool
First Run Setup | First Run
When an AI Agent uses this Skill for the first time, it MUST perform the following permission request (one-time only; no need to repeat afterward):
cd /data/sec-inspect && sudo python3 scripts/setup_permissions.py --auto
This will automatically:
- Detect AI tools already installed on the system (Claude Code, Qoder, OpenCode, Windsurf, Cursor, Gemini CLI, Trae)
- Configure the minimum permission set (sudo, read all, write workspace)
- Back up existing configurations
- Verify that permissions take effect
After configuration is complete, restart the AI tool to make it take effect permanently. Verify permissions:
cd /data/sec-inspect && python3 scripts/setup_permissions.py --verify
Quick Start | Quick Start
Complete workflow: permission request → environment initialization → execute scan → reflective verification → output results
Step 1: Environment initialization (first time)
cd /data/sec-inspect && sudo bash scripts/setup.sh
Automatically completes: detect/install Python >= 3.11, create workspace, install Skill to the AI tool directory.
Step 2: Execute scan
# 推荐（源码模式）
cd /data/sec-inspect && sudo python3 -m scripts.main --output-dir /data/sec-inspect/workspace
# 编译版（需 Python 3.11 精确匹配）
cd /data/sec-inspect && sudo python3 scripts/main.pyz --output-dir /data/sec-inspect/workspace
pyz failure handling: if the
bad magic numbererror occurs, see references/python-runtime.md
Step 3: View report
Report output to /data/sec-inspect/workspace/{YYYY-MM-DD}/report/：
| File | Format | Purpose |
|---|---|---|
sec-report-{date}.md |
Markdown | Main report: conclusions, evidence, timeline, remediation recommendations |
sec-report-{date}.json |
JSON | Structured data, convenient for programmatic processing |
attack-chain-{date}.md |
Markdown | Attack chain analysis |
sec-inspect-log-{date}.log |
Log | Execution log |
Step 4: Post-Scan Reflection（MANDATORY）
After the scan is complete, the reflection process must be executed first before reporting results to the user. See Post-Scan Reflection。
What Can It Do? | What Can It Do?
Detection Capabilities | Detection Capabilities
Covers 12 major detection categories、51 security analyzers、10 data collectors, mapped to 103+ MITRE ATT&CK techniques。
| Detection Category | Core Capability |
|---|---|
| Process anomalies | Hidden processes, reverse shells, process tree anomalies, code injection |
| Network anomalies | C2 communication, DNS tunneling, DGA domains, threat intelligence matching |
| Authentication and credentials | SSH backdoor keys, brute force attacks, PAM backdoors, credential leakage |
| Persistence mechanisms | Crontab/Systemd/Shell configuration backdoors |
| Rootkit | Kernel module anomalies, LD_PRELOAD hijacking, io_uring/eBPF rootkits |
| Malware | Cryptomining, ransomware, RATs, fileless malware |
| Memory forensics | Memory injection, RWX anomalies, memfd fileless attacks |
| File system | SUID/SGID anomalies, Webshells, hidden files |
| Lateral movement | SSH lateral movement, port forwarding, temporal correlation analysis |
| Containers/K8s | Container escape, RBAC risk, abnormal runtime behavior |
Full Detection Capability List(including full analyzer and collector details) see references/detection-capabilities.md
MITRE ATT&CK Technique Mapping Details(80+ technique IDs, 14 tactical phases) see references/technique-mappings.md
Key Features | Core Features
- 51 security analyzers — covering multi-dimensional detection such as traditional threats, container security, and memory forensics
- 10 data collectors — comprehensive collection of system/process/network/user/file/log/Cron/service/DNS/software package
- 103+ MITRE ATT&CK mappings — each alert is associated with an ATT&CK technique ID
- Environment adaptive — automatically identifies server roles and intelligently skips inapplicable detections
- Zero system modification — read-only operations, does not modify any system files
- IoC threat intelligence — built-in base64-encoded IoC database
- 3 deployment modes — standalone / docker / k8s
Prerequisites | Prerequisites
| Item | Requirement |
|---|---|
| Architecture | x86_64 (AMD64) |
| Operating System | Linux (glibc 2.17+: Ubuntu 14.04+, CentOS 7+, Debian 8+) |
| Python | >= 3.11（setup.sh can be installed automatically) |
| Permissions | root (sudo) |
| Network | Scanning requires no internet connection; when Python 3.11 is missing, network download is required (~30MB) |
Security Model | Security Model
- root (sudo) — reads kernel information such as /proc, /sys, and system logs
- Read-only collection — zero system modification, does not write/delete/modify any system files
- Writes are limited to workspace/ — only saves scan logs and reports
Required Permissions | Minimum Permission Set
{
"permissions": {
"allow": [
"Bash(sudo:*)",
"Bash(python3:*)",
"Read(**)",
"Write(/data/sec-inspect/workspace/**)",
"Write(workspace/**)"
]
}
}
Supported AI tools: Claude Code, QoderCLI, OpenCode, Windsurf, Cursor, Gemini CLI, Trae. See references/permissions.md。
Command Line | Command Line Reference
Core Parameters | Core Parameters
# 基本扫描
cd /data/sec-inspect && sudo python3 -m scripts.main --output-dir /data/sec-inspect/workspace
# 指定输出格式
cd /data/sec-inspect && sudo python3 -m scripts.main --format both
# 完整报告（含时间线、攻击链、交叉关联）
cd /data/sec-inspect && sudo python3 -m scripts.main --full-report
# 高负载时强制执行
cd /data/sec-inspect && sudo python3 -m scripts.main --force
# 列出所有分析器
cd /data/sec-inspect && python3 -m scripts.main --list-analyzers
# 查看资产数据
cd /data/sec-inspect && python3 -m scripts.main --show-assets all
# K8s 部署
cd /data/sec-inspect && python3 -m scripts.main k8s-deploy
All Parameters | Complete Parameter Table
| Parameter | Description | Default Value |
|---|---|---|
--output-dir PATH |
Report output directory | from config |
--format {markdown,json,both} |
Output format | both |
--quiet |
Silent mode, suitable for crontab | from config |
--force |
Skip load protection and force execution | — |
--list-analyzers |
List all analyzers and their execution time | — |
--show-assets [{all,ioc,whitelist}] |
Show decoded asset data | all |
--no-fp-suppression |
Disable false-positive suppression (audit mode) | — |
--force-json |
Force generation of JSON report | — |
--full-report |
Enable full report: timeline, attack chain, cross-correlation, coverage | — |
--lang {auto,en,zh,both} |
Report language | auto |
--env {auto,development,production,ci,container} |
Environment context | auto |
--retention-days N |
Report retention days | 180 |
--dry-run |
Preview only, no reporting | — |
Subcommands | Subcommands
| Subcommand | Purpose |
|---|---|
standalone |
Run in standalone mode (includes built-in LLM client) |
k8s-deploy |
K8s CronJob deployment, execution, result collection |
whitelist |
Whitelist management (learning + user-defined) |
perf |
Performance monitoring and analysis |
Deploy Modes | Deployment Modes
| Mode | Path | Description |
|---|---|---|
| standalone | deploy/standalone/ | Run directly on a single machine |
| docker | deploy/docker/ | Docker container, includes Dockerfile + compose |
| k8s | deploy/k8s/ | CronJob + RBAC + ConfigMap |
Understanding Results | Understanding Scan Results
Scan Conclusion | Scan Conclusion
| Conclusion | Meaning | Recommended Action |
|---|---|---|
| Compromised | Confirmed Compromise | Isolate immediately, perform P0 remediation |
| Highly Suspicious | Highly Suspicious | Investigate further, prepare P1 remediation |
| At Risk | At Risk | Plan remediation, strengthen monitoring |
| No Intrusion | No Compromise Found | Stay vigilant, scan regularly |
Alert Priority | Alert Priority
| Level | Response Time | Description |
|---|---|---|
| P0-Critical | Immediate | Confirmed compromise, requires urgent handling |
| P1-High | Within 24h | Highly suspicious, requires verification and remediation |
| P2-Medium | Within 1 week | Potential risk, optimization recommended |
| P3-Low | Planned | Improvement suggestions, security hardening |
Performance Constraints | Performance Constraints
| Metric | Constraint |
|---|---|
| Quick scan execution time | < 90s |
| Full scan execution time | < 10 min |
| CPU usage (single core) | < 50% (nice(19) + adaptive throttling) |
| Memory usage | < 200 MB |
| Load protection | Automatically exits when CPU > 70% or memory < 500MB (--force skipped) |
Post-Scan Reflection | Post-Scan Reflection
MANDATORY — Must be performed after every scan
After the scan is complete, the AI Agent must first perform the reflection process before outputting results to the user.
See the full process at references/post-run-reflection.md。
Phase 1: Alert Verification | Alert Verification
| Step | Operation | Key Point |
|---|---|---|
| 0 | Consult references/lessons-learned.md | Directly skip known false positives |
| 1 | Identify the runtime environment | WSL2/K8s/container/development machine |
| 2 | Verify each item with tools | Run a verification command for each alert |
| 3 | Summarize the determination | Distinguish real alerts vs false positives |
Quick Verification Commands | Quick Verification Commands
| Alert Type | Verification Command |
|---|---|
| Hidden process | sudo ls /proc/{pid}/exe -la |
| Suspicious port | sudo ss -tlnp | grep {port} |
| Anomalous file | sudo stat {path} && sudo file {path} |
| SSH key | sudo cat /root/.ssh/authorized_keys |
| Crontab | sudo crontab -l && sudo ls /etc/cron.d/ |
| Systemd service | sudo systemctl cat {service} |
| Kernel module | sudo lsmod | grep {module} |
| Network connection | sudo ss -anp | grep {ip/port} |
Common False Positive Patterns | Common False Positive Patterns
| Environment | Common False Positive | Judgment Basis |
|---|---|---|
| WSL2 | Kernel module alert | uname -r contains microsoft |
| Development machine | Node.js/Python process alert | The AI tool's own process |
| Docker Host | overlay filesystem alert | /var/lib/docker/overlay2 path |
| K8s Node | kubelet network alert | kube-system namespace |
| CI/CD | Temporary file alert | /tmp or /workspace path |
Phase 2: Functional Consistency | Functional Consistency
- Verify against this SKILL.md whether the feature promises match reality
- Fix inconsistencies immediately upon discovery
Core Rules | Core Rules
| Rule | Description |
|---|---|
| Verification takes precedence over reporting | Alerts that have not been verified with tools must not be reported to the user |
| Classifying based on experience is prohibited | Command output must serve as the basis for determination |
| "Suggest the user check" is prohibited | You must execute the command yourself and give a definitive conclusion |
| New false positives discovered must be recorded | Append to lessons-learned.md |
Multi-Skill Security Assessment | Multi-Skill Security Assessment
When the user asks about the overall security of the system, the AI Agent MUST coordinate all available security Skills.
Detailed protocol see references/call-other-sec-skills.md。
| Skill | Dimension | Invocation condition |
|---|---|---|
| sec-inspect | User-mode intrusion detection | Always invoke |
| sec-kernel | Kernel CVE vulnerability detection + PoC verification | available_skills Contains sec-kernel MUST invoke when |
Conclusion synthesis rule(take the most severe):
| sec-inspect | sec-kernel | Final conclusion |
|---|---|---|
| No Intrusion | No vulnerabilities | Safe |
| No Intrusion | VULNERABLE | At Risk |
| No Intrusion | EXPLOITABLE | At Risk (Critical) |
| At Risk+ | EXPLOITABLE | Highly Suspicious |
| Compromised | Any | Compromised |
Trigger Scenarios | Trigger Scenarios
When the following scenarios occur, be sure to proactively invoke this skill:
- The user asks whether the server has been compromised or is secure
- A security audit or compliance check is needed
- Suspicious processes, files, or network connections are found
- The user mentions keywords such as "security check", "intrusion detection", "backdoor", "trojan", "mining", "Rootkit", "Webshell", etc.
- Security incident response and forensic analysis
- Even if the user only says "check the server" or "see if there are any problems with the system", you should proactively suggest using this skill
- When the user asks about abnormal processes, abnormal network connections, or abnormal logins
- When it is necessary to determine whether an alert is a false positive
For AI Agents | Usage Principles
- Proactive suggestion — When the user mentions security issues, proactively suggest running sec-inspect
- Scan before answering — Do not judge based on experience; verify with tools first
- Reflection filtering — Post-Scan Reflection must be executed before reporting
- Evidence-oriented — Every alert must have specific evidence and remediation suggestions
- Clear priorities — Report by P0/P1/P2/P3 severity levels
- Python runtime — When pyz fails, MUST follow references/python-runtime.md to obtain Python 3.11
- Multi-Skill coordination — When security Skills such as sec-kernel are available, MUST invoke them
Absolute Prohibitions | Absolute Prohibitions
- Reporting alerts to the user without executing verification commands
- Saying "suggest the user check" instead of confirming yourself
- Outputting the report first and adding verification afterward
- Giving up scanning after pyz fails (MUST obtain Python 3.11)
- Giving a "system is secure" conclusion without invoking sec-kernel when it is available
Troubleshooting | Troubleshooting
| Problem | Cause | Solutions |
|---|---|---|
| Insufficient permissions | sudo not used | sudo python3 -m scripts.main |
| Scan timeout | System load too high | Add --force |
| No output file | Output directory does not exist | mkdir -p /data/sec-inspect/workspace |
| pyz bad magic number | Incompatible Python version | See references/python-runtime.md |
| Insufficient Python version | < 3.11 | sudo bash scripts/setup.sh |
| Failed to load asset data | assets/ abnormal | python3 -m scripts.main --show-assets all |
License & Credits
- License: MIT License
- Contributors: See
CONTRIBUTOR.md - References: UAC, OSSEC, Wazuh, rkhunter, chkrootkit, Falco
- ATT&CK: MITRE ATT&CK Framework v18