From d3fa5ea1326d10ea135a74e0542826e2b6db2626 Mon Sep 17 00:00:00 2001 From: CarterPerez-dev Date: Sat, 11 Apr 2026 05:38:49 -0400 Subject: [PATCH] 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. --- .../linux-ebpf-security-tracer/README.md | 188 ++++-------------- PROJECTS/intermediate/dlp-scanner/README.md | 7 +- PROJECTS/intermediate/dlp-scanner/justfile | 27 +++ README.md | 10 +- 4 files changed, 80 insertions(+), 152 deletions(-) create mode 100644 PROJECTS/intermediate/dlp-scanner/justfile diff --git a/PROJECTS/beginner/linux-ebpf-security-tracer/README.md b/PROJECTS/beginner/linux-ebpf-security-tracer/README.md index c562ea44..b6ceabcc 100644 --- a/PROJECTS/beginner/linux-ebpf-security-tracer/README.md +++ b/PROJECTS/beginner/linux-ebpf-security-tracer/README.md @@ -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. +[![Cybersecurity Projects](https://img.shields.io/badge/Cybersecurity--Projects-Project%20%2322-red?style=flat&logo=github)](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/beginner/linux-ebpf-security-tracer) +[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white)](https://python.org) +[![C](https://img.shields.io/badge/C-eBPF-A8B9CC?style=flat&logo=c&logoColor=black)](https://ebpf.io) +[![License: AGPLv3](https://img.shields.io/badge/License-AGPL_v3-purple.svg)](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 diff --git a/PROJECTS/intermediate/dlp-scanner/README.md b/PROJECTS/intermediate/dlp-scanner/README.md index 4bcedf04..f6b1cf6f 100644 --- a/PROJECTS/intermediate/dlp-scanner/README.md +++ b/PROJECTS/intermediate/dlp-scanner/README.md @@ -7,7 +7,7 @@ ╚═════╝ ╚══════╝╚═╝ ╚══════╝ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ``` -[![Cybersecurity Projects](https://img.shields.io/badge/Cybersecurity--Projects-intermediate-red?style=flat&logo=github)](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/intermediate/dlp-scanner) +[![Cybersecurity Projects](https://img.shields.io/badge/Cybersecurity--Projects-Project%20%2323-red?style=flat&logo=github)](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/intermediate/dlp-scanner) [![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat&logo=python&logoColor=white)](https://python.org) [![License: AGPLv3](https://img.shields.io/badge/License-AGPL_v3-purple.svg)](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 diff --git a/PROJECTS/intermediate/dlp-scanner/justfile b/PROJECTS/intermediate/dlp-scanner/justfile new file mode 100644 index 00000000..577732af --- /dev/null +++ b/PROJECTS/intermediate/dlp-scanner/justfile @@ -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 diff --git a/README.md b/README.md index e792ecc3..2d1ccbbe 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,11 @@

View Complete Projects:

- Projects + Projects
-

Currently building: project #22

+

Currently building: project #24

--- @@ -70,7 +70,7 @@ Tools, courses, certifications, communities, and frameworks for cybersecurity pr | **[Base64 Encoder/Decoder](./SYNOPSES/beginner/Base64.Encoder.Decoder.md)**
Multi-format encoding tool | ![1h](https://img.shields.io/badge/⏱️_2h-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | Base64/32 encoding • URL encoding • Auto-detection
[Source Code](./PROJECTS/beginner/base64-tool) \| [Docs](./PROJECTS/beginner/base64-tool/learn) | | **[Linux CIS Hardening Auditor](./SYNOPSES/beginner/Linux.CIS.Hardening.Auditor.md)**
CIS benchmark compliance checker | ![3-4h](https://img.shields.io/badge/⏱️_6--8h-blue) ![Bash](https://img.shields.io/badge/Bash-4EAA25?logo=gnubash&logoColor=white) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | CIS benchmarks • System hardening • Compliance scoring • Shell scripting
[Learn More](./SYNOPSES/beginner/Linux.CIS.Hardening.Auditor.md) | | **[Systemd Persistence Scanner](./SYNOPSES/beginner/Systemd.Persistence.Scanner.md)**
Hunt Linux persistence mechanisms | ![2-3h](https://img.shields.io/badge/⏱️_6--8h-blue) ![Go](https://img.shields.io/badge/Go-00ADD8?logo=go&logoColor=white) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | Persistence techniques • Systemd internals • Cron analysis • Threat hunting
[Learn More](./SYNOPSES/beginner/Systemd.Persistence.Scanner.md) | -| **[Linux eBPF Security Tracer](./SYNOPSES/beginner/Linux.eBPF.Security.Tracer.md)**
Real-time syscall tracing with eBPF | ![2-3h](https://img.shields.io/badge/⏱️_10--12h-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![C](https://img.shields.io/badge/C-A8B9CC?logo=c&logoColor=black) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | eBPF programs • Syscall tracing • BCC framework • Security observability
[Learn More](./SYNOPSES/beginner/Linux.eBPF.Security.Tracer.md) | +| **[Linux eBPF Security Tracer](./PROJECTS/beginner/linux-ebpf-security-tracer)**
Real-time syscall tracing with eBPF | ![2-3h](https://img.shields.io/badge/⏱️_10--12h-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![C](https://img.shields.io/badge/C-A8B9CC?logo=c&logoColor=black) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | eBPF programs • Syscall tracing • BCC framework • Security observability
[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)**
Educational malware lifecycle demo | ![2-3h](https://img.shields.io/badge/⏱️_8--10h-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | Trojan anatomy • Data exfiltration • File encryption • Attack lifecycle
[Learn More](./SYNOPSES/beginner/Trojan.Application.Builder.md) | | **[DNS Sinkhole](./SYNOPSES/beginner/DNS.Sinkhole.md)**
Pi-hole-style malware domain blocker | ![3-4h](https://img.shields.io/badge/⏱️_10--12h-blue) ![Go](https://img.shields.io/badge/Go-00ADD8?logo=go&logoColor=white) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | DNS protocol • Blocklist management • Query logging • Network defense
[Learn More](./SYNOPSES/beginner/DNS.Sinkhole.md) | | **[Firewall Rule Engine](./PROJECTS/beginner/firewall-rule-engine)**
Parse and validate iptables/nftables rules | ![2-3h](https://img.shields.io/badge/⏱️_6--8h-blue) ![V](https://img.shields.io/badge/V-5D87BF?logo=v&logoColor=white) ![Beginner](https://img.shields.io/badge/●_Beginner-green) | Firewall internals • Rule parsing • iptables/nftables • V language
[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)**
Internet-connected device search engine | ![3-5d](https://img.shields.io/badge/⏱️_3--5d-blue) ![Go](https://img.shields.io/badge/Go-00ADD8?logo=go&logoColor=white) ![React](https://img.shields.io/badge/React-61DAFB?logo=react&logoColor=black) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | Service fingerprinting • Network scanning • OSINT • Search engine design
[Learn More](./SYNOPSES/intermediate/Self.Hosted.Shodan.Clone.md) | | **[JA3/JA4 TLS Fingerprinting Tool](./SYNOPSES/intermediate/JA3.JA4.TLS.Fingerprinting.Tool.md)**
Fingerprint TLS clients by handshake | ![2-4d](https://img.shields.io/badge/⏱️_2--4d-blue) ![Rust](https://img.shields.io/badge/Rust-000000?logo=rust&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | TLS handshake analysis • JA3/JA4 hashing • Bot detection • Malware C2 identification
[Learn More](./SYNOPSES/intermediate/JA3.JA4.TLS.Fingerprinting.Tool.md) | | **[Mobile App Security Analyzer](./SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md)**
Decompile and analyze mobile apps | ![3-5d](https://img.shields.io/badge/⏱️_3--5d-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | APK/IPA analysis • Reverse engineering • OWASP Mobile
[Learn More](./SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md) | -| **[DLP Scanner](./SYNOPSES/intermediate/DLP.Scanner.md)**
Data Loss Prevention for files, DBs, and traffic | ![2-4d](https://img.shields.io/badge/⏱️_2--4d-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | PII detection • GDPR/HIPAA compliance • Pattern matching • Data classification
[Learn More](./SYNOPSES/intermediate/DLP.Scanner.md) | +| **[DLP Scanner](./PROJECTS/intermediate/dlp-scanner)**
Data Loss Prevention for files, DBs, and traffic | ![2-4d](https://img.shields.io/badge/⏱️_2--4d-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | PII detection • GDPR/HIPAA compliance • Pattern matching • Data classification
[Source Code](./PROJECTS/intermediate/dlp-scanner) \| [Docs](./PROJECTS/intermediate/dlp-scanner/learn) | | **[Lua/Nginx Edge Backend](./SYNOPSES/intermediate/Lua.Nginx.Edge.Backend.md)**
Full CRUD backend via Lua in Nginx | ![3-5d](https://img.shields.io/badge/⏱️_3--5d-blue) ![Lua](https://img.shields.io/badge/Lua-2C2D72?logo=lua&logoColor=white) ![Nginx](https://img.shields.io/badge/Nginx-009639?logo=nginx&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | Edge computing • OpenResty • Lua scripting • WAF • JWT at the edge
[Learn More](./SYNOPSES/intermediate/Lua.Nginx.Edge.Backend.md) | | **[Privesc Playground](./SYNOPSES/intermediate/Privesc.Playground.md)**
20+ privilege escalation paths to exploit | ![3-5d](https://img.shields.io/badge/⏱️_3--5d-blue) ![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | SUID exploitation • Sudo abuse • Cron hijacking • GTFOBins • Capability abuse
[Learn More](./SYNOPSES/intermediate/Privesc.Playground.md) | | **[SBOM Generator & Vulnerability Matcher](./SYNOPSES/intermediate/SBOM.Generator.md)**
Software Bill of Materials with CVE matching | ![2-4d](https://img.shields.io/badge/⏱️_2--4d-blue) ![Go](https://img.shields.io/badge/Go-00ADD8?logo=go&logoColor=white) ![Intermediate](https://img.shields.io/badge/●_Intermediate-yellow) | SPDX/CycloneDX formats • Dependency analysis • CVE databases • EO 14028 compliance
[Learn More](./SYNOPSES/intermediate/SBOM.Generator.md) | @@ -141,4 +141,4 @@ Tools, courses, certifications, communities, and frameworks for cybersecurity pr ## License -AGPL 3.0 \ No newline at end of file +AGPL 3.0