fix: update READMEs for ebpf tracer & dlp scanner
Add ASCII art, project number badges, justfile tip, and learn module links. Add missing justfile to dlp-scanner. Update main README with source code links and bump project count to 23/67.
This commit is contained in:
CarterPerez-dev
parent
db3e25e886
commit
d3fa5ea132
|
|
@ -1,68 +1,52 @@
|
|||
# Linux eBPF Security Tracer
|
||||
```ruby
|
||||
███████╗██████╗ ██████╗ ███████╗ ████████╗██████╗ █████╗ ██████╗███████╗██████╗
|
||||
██╔════╝██╔══██╗██╔══██╗██╔════╝ ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗
|
||||
█████╗ ██████╔╝██████╔╝█████╗ ██║ ██████╔╝███████║██║ █████╗ ██████╔╝
|
||||
██╔══╝ ██╔══██╗██╔═══╝ ██╔══╝ ██║ ██╔══██╗██╔══██║██║ ██╔══╝ ██╔══██╗
|
||||
███████╗██████╔╝██║ ██║ ██║ ██║ ██║██║ ██║╚██████╗███████╗██║ ██║
|
||||
╚══════╝╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝ ╚═╝
|
||||
```
|
||||
|
||||
Real-time syscall tracing tool using eBPF for security observability. Monitors process execution, file access, network connections, privilege changes, and system operations to detect suspicious behavior patterns.
|
||||
[](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/beginner/linux-ebpf-security-tracer)
|
||||
[](https://python.org)
|
||||
[](https://ebpf.io)
|
||||
[](https://www.gnu.org/licenses/agpl-3.0)
|
||||
|
||||
## Features
|
||||
> Real-time syscall tracing tool using eBPF for security observability — monitors process execution, file access, network connections, privilege changes, and system operations to detect suspicious behavior.
|
||||
|
||||
- Real-time syscall monitoring via eBPF tracepoints
|
||||
*This is a quick overview — security theory, architecture, and full walkthroughs are in the [learn modules](#learn).*
|
||||
|
||||
## What It Does
|
||||
|
||||
- Real-time syscall monitoring via eBPF tracepoints (process, file, network, privilege, system)
|
||||
- 10 built-in detection rules mapped to MITRE ATT&CK techniques
|
||||
- Correlated event analysis (reverse shell detection, privilege escalation)
|
||||
- Correlated event analysis for multi-step attacks (reverse shell detection, privilege escalation chains)
|
||||
- Multiple output formats: live color-coded stream, JSON, table summary
|
||||
- Configurable severity filtering (LOW, MEDIUM, HIGH, CRITICAL)
|
||||
- Process, file, network, privilege, and system event categories
|
||||
- Event enrichment from /proc filesystem
|
||||
- Event enrichment from /proc filesystem (parent process, username)
|
||||
- Clean signal handling and eBPF program cleanup
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Linux kernel 5.8+ (ring buffer support)
|
||||
- Root privileges (required for eBPF)
|
||||
- Python 3.10+
|
||||
- BCC (BPF Compiler Collection) with Python bindings
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install system dependencies and Python packages
|
||||
./install.sh
|
||||
|
||||
# Start tracing all syscalls
|
||||
sudo uv run ebpf-tracer
|
||||
|
||||
# JSON output, only MEDIUM+ severity
|
||||
sudo uv run ebpf-tracer -f json -s MEDIUM
|
||||
|
||||
# Only network events
|
||||
sudo uv run ebpf-tracer -t network
|
||||
|
||||
# Only show detection alerts
|
||||
sudo uv run ebpf-tracer --detections
|
||||
|
||||
# Filter by process name
|
||||
sudo uv run ebpf-tracer -c nginx
|
||||
|
||||
# Write events to file while streaming
|
||||
sudo uv run ebpf-tracer -o events.jsonl
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> This project uses [`just`](https://github.com/casey/just) as a command runner. Type `just` to see all available commands.
|
||||
>
|
||||
> Install: `curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin`
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
ebpf-tracer [OPTIONS]
|
||||
|
||||
Options:
|
||||
-f, --format Output format: json, table, live [default: live]
|
||||
-s, --severity Minimum severity: LOW, MEDIUM, [default: LOW]
|
||||
HIGH, CRITICAL
|
||||
-p, --pid Filter by specific PID
|
||||
-c, --comm Filter by process name
|
||||
-t, --type Event category: process, file, [default: all]
|
||||
network, privilege, system, all
|
||||
--no-enrich Disable /proc enrichment
|
||||
-o, --output Also write events to file
|
||||
--detections Show only detection alerts
|
||||
--version Show version
|
||||
--help Show help
|
||||
```bash
|
||||
sudo uv run ebpf-tracer # trace all syscalls (live mode)
|
||||
sudo uv run ebpf-tracer -f json -s MEDIUM # JSON output, MEDIUM+ severity
|
||||
sudo uv run ebpf-tracer -t network # only network events
|
||||
sudo uv run ebpf-tracer --detections # only show detection alerts
|
||||
sudo uv run ebpf-tracer -c nginx # filter by process name
|
||||
sudo uv run ebpf-tracer -o events.jsonl # write events to file while streaming
|
||||
```
|
||||
|
||||
## Detection Rules
|
||||
|
|
@ -80,106 +64,18 @@ Options:
|
|||
| D009 | Log Tampering | MEDIUM | T1070.002 | Log file deletion/truncation |
|
||||
| D010 | Suspicious Mount | HIGH | T1611 | mount syscall |
|
||||
|
||||
## Architecture
|
||||
## Learn
|
||||
|
||||
```
|
||||
User Space
|
||||
┌─────────┐ ┌──────────────┐ ┌─────────────────┐
|
||||
│ CLI │──▶│ Event Engine │──▶│ Output Renderer │
|
||||
│ (Typer) │ │ (Processor + │ │ (JSON / Table / │
|
||||
│ │ │ Detector) │ │ Live Stream) │
|
||||
└─────────┘ └──────┬───────┘ └─────────────────┘
|
||||
│
|
||||
┌──────┴───────┐
|
||||
│ BPF Loader │
|
||||
│ (BCC/Python)│
|
||||
└──────┬───────┘
|
||||
─────────────────────┼──────────────────────────────
|
||||
Kernel Space │
|
||||
┌──────┴───────┐
|
||||
│ Ring Buffer │
|
||||
└──────┬───────┘
|
||||
┌───────────────┼───────────────────┐
|
||||
│ eBPF C Tracepoint Programs │
|
||||
│ ┌─────────┐┌────────┐┌─────────┐ │
|
||||
│ │ Process ││ File ││ Network │ │
|
||||
│ └─────────┘└────────┘└─────────┘ │
|
||||
│ ┌──────────┐┌────────┐ │
|
||||
│ │Privilege ││ System │ │
|
||||
│ └──────────┘└────────┘ │
|
||||
└───────────────────────────────────┘
|
||||
```
|
||||
This project includes step-by-step learning materials covering security theory, architecture, and implementation.
|
||||
|
||||
## Monitored Syscalls
|
||||
|
||||
| Category | Syscalls | Purpose |
|
||||
|----------|----------|---------|
|
||||
| Process | execve, clone | New process creation |
|
||||
| File | openat, unlinkat, renameat2 | File access and manipulation |
|
||||
| Network | connect, accept4, bind, listen | Network activity |
|
||||
| Privilege | setuid, setgid | Privilege changes |
|
||||
| System | ptrace, mount, init_module | System-level operations |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── main.py # CLI entrypoint (Typer)
|
||||
├── config.py # Constants, event types, detection rules
|
||||
├── loader.py # BCC program loader and ring buffer setup
|
||||
├── processor.py # Event parsing, enrichment, filtering
|
||||
├── detector.py # Detection engine with stateless and stateful rules
|
||||
├── renderer.py # Output formatters (JSON, live, table)
|
||||
└── ebpf/
|
||||
├── process_tracer.c # execve, clone tracepoints
|
||||
├── file_tracer.c # openat, unlinkat, renameat2 tracepoints
|
||||
├── network_tracer.c # connect, accept4, bind, listen tracepoints
|
||||
├── privilege_tracer.c # setuid, setgid tracepoints
|
||||
└── system_tracer.c # ptrace, mount, init_module tracepoints
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
### Live Mode (default)
|
||||
|
||||
```
|
||||
[14:30:01] LOW execve pid=1234 comm=bash /usr/bin/curl
|
||||
[14:30:01] CRITICAL connect pid=1234 comm=nc 10.0.0.1:4444 [Reverse Shell]
|
||||
[14:30:02] MEDIUM openat pid=5678 comm=python3 /etc/shadow [Sensitive File Read]
|
||||
[14:30:03] HIGH init_module pid=9012 comm=insmod [Kernel Module Load]
|
||||
```
|
||||
|
||||
### JSON Mode
|
||||
|
||||
```json
|
||||
{"timestamp":"2026-04-08T14:30:01+00:00","event_type":"connect","pid":1234,"comm":"nc","severity":"CRITICAL","detection":"Reverse Shell","mitre_id":"T1059.004","dest_ip":"10.0.0.1","dest_port":4444}
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Install dev dependencies
|
||||
uv sync
|
||||
|
||||
# Run unit tests
|
||||
just test
|
||||
|
||||
# Lint
|
||||
just lint
|
||||
|
||||
# Format
|
||||
just format
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **eBPF C programs** attach to kernel tracepoints for specific syscalls
|
||||
2. When a traced syscall fires, the eBPF program captures event data (PID, UID, filename, etc.) and pushes it to a shared ring buffer
|
||||
3. **Python (BCC)** polls the ring buffer and deserializes events via ctypes
|
||||
4. The **processor** enriches events with data from /proc (parent process, username)
|
||||
5. The **detection engine** evaluates each event against stateless rules (single-event patterns) and stateful rules (correlated event sequences)
|
||||
6. The **renderer** outputs events in the selected format with severity-based color coding
|
||||
| Module | Topic |
|
||||
|--------|-------|
|
||||
| [00 - Overview](learn/00-OVERVIEW.md) | Prerequisites and quick start |
|
||||
| [01 - Concepts](learn/01-CONCEPTS.md) | eBPF theory and security observability |
|
||||
| [02 - Architecture](learn/02-ARCHITECTURE.md) | System design and data flow |
|
||||
| [03 - Implementation](learn/03-IMPLEMENTATION.md) | Code walkthrough |
|
||||
| [04 - Challenges](learn/04-CHALLENGES.md) | Extension ideas and exercises |
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
AGPL 3.0
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
╚═════╝ ╚══════╝╚═╝ ╚══════╝ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═══╝
|
||||
```
|
||||
|
||||
[](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/intermediate/dlp-scanner)
|
||||
[](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/intermediate/dlp-scanner)
|
||||
[](https://python.org)
|
||||
[](https://www.gnu.org/licenses/agpl-3.0)
|
||||
|
||||
|
|
@ -31,6 +31,11 @@ bash install.sh
|
|||
dlp-scan file ./data
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> This project uses [`just`](https://github.com/casey/just) as a command runner. Type `just` to see all available commands.
|
||||
>
|
||||
> Install: `curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin`
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
# ©AngelaMos | 2026
|
||||
# justfile
|
||||
|
||||
default:
|
||||
@just --list
|
||||
|
||||
lint:
|
||||
uv run ruff check .
|
||||
uv run mypy src/
|
||||
|
||||
format:
|
||||
uv run yapf -r -i src/ tests/
|
||||
|
||||
check-format:
|
||||
uv run yapf -r -d src/ tests/
|
||||
|
||||
test:
|
||||
uv run pytest tests/ -m "unit"
|
||||
|
||||
test-all:
|
||||
uv run pytest tests/
|
||||
|
||||
run *ARGS:
|
||||
uv run dlp-scan {{ARGS}}
|
||||
|
||||
install:
|
||||
bash install.sh
|
||||
10
README.md
10
README.md
|
|
@ -25,11 +25,11 @@
|
|||
<h2 align="center"><strong>View Complete Projects:</strong></h2>
|
||||
<div align="center">
|
||||
<a href="https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS">
|
||||
<img src="https://img.shields.io/badge/Full_Source_Code-21/67-blue?style=for-the-badge&logo=github" alt="Projects"/>
|
||||
<img src="https://img.shields.io/badge/Full_Source_Code-23/67-blue?style=for-the-badge&logo=github" alt="Projects"/>
|
||||
</a>
|
||||
</div>
|
||||
|
||||
<p align="center"><sub><em>Currently building: project #22</em></sub></p>
|
||||
<p align="center"><sub><em>Currently building: project #24</em></sub></p>
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ Tools, courses, certifications, communities, and frameworks for cybersecurity pr
|
|||
| **[Base64 Encoder/Decoder](./SYNOPSES/beginner/Base64.Encoder.Decoder.md)**<br>Multi-format encoding tool |    | Base64/32 encoding • URL encoding • Auto-detection<br>[Source Code](./PROJECTS/beginner/base64-tool) \| [Docs](./PROJECTS/beginner/base64-tool/learn) |
|
||||
| **[Linux CIS Hardening Auditor](./SYNOPSES/beginner/Linux.CIS.Hardening.Auditor.md)**<br>CIS benchmark compliance checker |    | CIS benchmarks • System hardening • Compliance scoring • Shell scripting<br>[Learn More](./SYNOPSES/beginner/Linux.CIS.Hardening.Auditor.md) |
|
||||
| **[Systemd Persistence Scanner](./SYNOPSES/beginner/Systemd.Persistence.Scanner.md)**<br>Hunt Linux persistence mechanisms |    | Persistence techniques • Systemd internals • Cron analysis • Threat hunting<br>[Learn More](./SYNOPSES/beginner/Systemd.Persistence.Scanner.md) |
|
||||
| **[Linux eBPF Security Tracer](./SYNOPSES/beginner/Linux.eBPF.Security.Tracer.md)**<br>Real-time syscall tracing with eBPF |     | eBPF programs • Syscall tracing • BCC framework • Security observability<br>[Learn More](./SYNOPSES/beginner/Linux.eBPF.Security.Tracer.md) |
|
||||
| **[Linux eBPF Security Tracer](./PROJECTS/beginner/linux-ebpf-security-tracer)**<br>Real-time syscall tracing with eBPF |     | eBPF programs • Syscall tracing • BCC framework • Security observability<br>[Source Code](./PROJECTS/beginner/linux-ebpf-security-tracer) \| [Docs](./PROJECTS/beginner/linux-ebpf-security-tracer/learn) |
|
||||
| **[Trojan Application Builder](./SYNOPSES/beginner/Trojan.Application.Builder.md)**<br>Educational malware lifecycle demo |    | Trojan anatomy • Data exfiltration • File encryption • Attack lifecycle<br>[Learn More](./SYNOPSES/beginner/Trojan.Application.Builder.md) |
|
||||
| **[DNS Sinkhole](./SYNOPSES/beginner/DNS.Sinkhole.md)**<br>Pi-hole-style malware domain blocker |    | DNS protocol • Blocklist management • Query logging • Network defense<br>[Learn More](./SYNOPSES/beginner/DNS.Sinkhole.md) |
|
||||
| **[Firewall Rule Engine](./PROJECTS/beginner/firewall-rule-engine)**<br>Parse and validate iptables/nftables rules |    | Firewall internals • Rule parsing • iptables/nftables • V language<br>[Source Code](./PROJECTS/beginner/firewall-rule-engine) \| [Docs](./PROJECTS/beginner/firewall-rule-engine/learn) |
|
||||
|
|
@ -96,7 +96,7 @@ Tools, courses, certifications, communities, and frameworks for cybersecurity pr
|
|||
| **[Self-Hosted Shodan Clone](./SYNOPSES/intermediate/Self.Hosted.Shodan.Clone.md)**<br>Internet-connected device search engine |     | Service fingerprinting • Network scanning • OSINT • Search engine design<br>[Learn More](./SYNOPSES/intermediate/Self.Hosted.Shodan.Clone.md) |
|
||||
| **[JA3/JA4 TLS Fingerprinting Tool](./SYNOPSES/intermediate/JA3.JA4.TLS.Fingerprinting.Tool.md)**<br>Fingerprint TLS clients by handshake |    | TLS handshake analysis • JA3/JA4 hashing • Bot detection • Malware C2 identification<br>[Learn More](./SYNOPSES/intermediate/JA3.JA4.TLS.Fingerprinting.Tool.md) |
|
||||
| **[Mobile App Security Analyzer](./SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md)**<br>Decompile and analyze mobile apps |    | APK/IPA analysis • Reverse engineering • OWASP Mobile<br>[Learn More](./SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md) |
|
||||
| **[DLP Scanner](./SYNOPSES/intermediate/DLP.Scanner.md)**<br>Data Loss Prevention for files, DBs, and traffic |    | PII detection • GDPR/HIPAA compliance • Pattern matching • Data classification<br>[Learn More](./SYNOPSES/intermediate/DLP.Scanner.md) |
|
||||
| **[DLP Scanner](./PROJECTS/intermediate/dlp-scanner)**<br>Data Loss Prevention for files, DBs, and traffic |    | PII detection • GDPR/HIPAA compliance • Pattern matching • Data classification<br>[Source Code](./PROJECTS/intermediate/dlp-scanner) \| [Docs](./PROJECTS/intermediate/dlp-scanner/learn) |
|
||||
| **[Lua/Nginx Edge Backend](./SYNOPSES/intermediate/Lua.Nginx.Edge.Backend.md)**<br>Full CRUD backend via Lua in Nginx |     | Edge computing • OpenResty • Lua scripting • WAF • JWT at the edge<br>[Learn More](./SYNOPSES/intermediate/Lua.Nginx.Edge.Backend.md) |
|
||||
| **[Privesc Playground](./SYNOPSES/intermediate/Privesc.Playground.md)**<br>20+ privilege escalation paths to exploit |    | SUID exploitation • Sudo abuse • Cron hijacking • GTFOBins • Capability abuse<br>[Learn More](./SYNOPSES/intermediate/Privesc.Playground.md) |
|
||||
| **[SBOM Generator & Vulnerability Matcher](./SYNOPSES/intermediate/SBOM.Generator.md)**<br>Software Bill of Materials with CVE matching |    | SPDX/CycloneDX formats • Dependency analysis • CVE databases • EO 14028 compliance<br>[Learn More](./SYNOPSES/intermediate/SBOM.Generator.md) |
|
||||
|
|
@ -141,4 +141,4 @@ Tools, courses, certifications, communities, and frameworks for cybersecurity pr
|
|||
|
||||
## License
|
||||
|
||||
AGPL 3.0
|
||||
AGPL 3.0
|
||||
|
|
|
|||
Loading…
Reference in New Issue