███████╗███████╗███╗   ██╗████████╗██╗███╗   ██╗███████╗██╗     ██╗  ██╗
██╔════╝██╔════╝████╗  ██║╚══██╔══╝██║████╗  ██║██╔════╝██║     ╚██╗██╔╝
███████╗█████╗  ██╔██╗ ██║   ██║   ██║██╔██╗ ██║█████╗  ██║      ╚███╔╝ 
╚════██║██╔══╝  ██║╚██╗██║   ██║   ██║██║╚██╗██║██╔══╝  ██║      ██╔██╗ 
███████║███████╗██║ ╚████║   ██║   ██║██║ ╚████║███████╗███████╗██╔╝ ██╗
╚══════╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝╚═╝  ╚═╝
                          🦁 CYBER SAMURAI FRAMEWORK 🦁

SentinelX is a production-ready Python framework for offensive and defensive security operations across Web2 and Web3 environments. It provides a comprehensive suite of security tools with a modern CLI interface, workflow orchestration, and extensible plugin architecture.

🎯 Mission: Guard digital infrastructure like a black ops cyber samurai. Hunt vulnerabilities. Neutralize threats. Optimize defenses. Operate with zero tolerance for sloppy security.

See SENTINELX_MASTER_PROMPT.md for the complete operational framework.

• 21 Security Tasks across all major security domains (14 original + 7 advanced pwn tasks)
• Advanced Pwn Toolkit with buffer overflows, ROP chains, heap exploitation, and shellcode generation
• Workflow Orchestration with dependency management and error handling
• Professional CLI Interface with rich formatting and interactive modes
• Plugin Architecture for easy extension and customization
• Advanced Reporting with multiple output formats
• Performance Profiling and benchmarking tools
• Docker Integration for sandboxed execution
• Configuration Management with validation and templates

• 🔒 Smart Contract Auditing (Slither, Mythril, CVSS)
• 💥 Advanced Binary Exploitation (Buffer overflows, ROP chains, Heap exploitation, Shellcode generation)
• 🎯 Comprehensive Pwn Toolkit (Automated exploitation, Multi-technique analysis, CTF-ready)
• ⛓️ Blockchain Security (Chain monitoring, Transaction analysis)
• 🎭 Red Team Operations (C2, Advanced lateral movement with pwncat-cs, Comprehensive social engineering campaigns)
• 🔍 Digital Forensics (Memory, Disk, Blockchain IR)
• 🤖 AI Security (LLM assistance, Prompt injection testing)
• 🌐 Web Security (Static analysis, Vulnerability scanning)

sentinelx/
├── sentinelx/              # Core framework code
│   ├── core/              # Framework core (tasks, registry, context)
│   ├── audit/             # Smart contract auditing tasks
│   ├── exploit/           # Exploit development tools
│   ├── blockchain/        # Blockchain security tools
│   ├── redteam/           # Red team operation tools
│   ├── forensic/          # Digital forensics tools
│   ├── ai/                # AI-powered security tools
│   └── cli.py             # Command-line interface
├── docs/                  # Comprehensive documentation
│   ├── USER_GUIDE.md      # User guide and tutorials
│   ├── DEVELOPER_GUIDE.md # Developer and extension guide
│   ├── API_REFERENCE.md   # Complete API documentation
│   └── TASK_REFERENCE.md  # Task reference guide
├── examples/              # Examples and tutorials
│   ├── workflows/         # Workflow templates
│   └── custom_tasks/      # Custom task examples
├── tests/                 # Test suite
├── scripts/               # Utility scripts
├── dev/                   # Development files and reports
├── logs/                  # Application logs
├── config.yaml.example    # Configuration template
└── requirements.txt       # Dependencies

# Clone the repository
git clone https://github.com/your-org/sentinelx.git
cd sentinelx

# Install in development mode
pip install -e .

# Verify installation
python -c "import sentinelx; print('✅ SentinelX installed successfully')"

# List all available tasks
sentinelx list

# Get information about a specific task
sentinelx info slither

# Run a task
sentinelx run cvss -p "{vector: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'}"

# Interactive mode
sentinelx interactive

# Search for tasks
sentinelx search "smart contract"

# Generate a workflow template
sentinelx workflow template audit_workflow.yaml --type audit

# Run the workflow
sentinelx workflow run audit_workflow.yaml

# List available workflows
sentinelx workflow list

SentinelX follows a modular architecture with clear separation of concerns:

sentinelx/
├── core/           # Core framework components
│   ├── registry.py # Plugin registration system
│   ├── task.py     # Base task class and interfaces
│   ├── context.py  # Execution context and configuration
│   ├── workflow.py # Workflow orchestration engine
│   └── utils.py    # Utility functions
├── audit/          # Smart contract auditing tasks
├── exploit/        # Exploit development tools
├── blockchain/     # Blockchain security tools
├── redteam/        # Red team operation tools
├── forensic/       # Digital forensics tools
├── ai/             # AI-powered security tools
├── cli.py          # Command-line interface
└── __init__.py     # Package initialization

• list - List all registered tasks with categorization
• info <task> - Detailed information about a specific task
• run <task> - Execute a security task
• search <query> - Search tasks by name or description
• validate - Validate tasks and configuration
• interactive - Interactive task execution mode
• config - Configuration management utilities
• version - Show version information

• workflow run <file> - Execute workflow from file
• workflow template <file> - Generate workflow templates
• workflow list - List available workflows and tasks

• docker setup - Setup Docker environment
• docker run <task> - Run tasks in containers
• perf profile <task> - Performance profiling
• perf benchmark <tasks> - Benchmark multiple tasks
• report generate <file> - Generate professional reports

Create a configuration file to customize SentinelX:

# Initialize configuration interactively
sentinelx config init

# Show current configuration
sentinelx config show

# Validate configuration
sentinelx config validate

Example configuration:

version: "1.0"
debug: false
log_level: "INFO"
output_dir: "./outputs"
temp_dir: "./temp"

blockchain:
  ethereum_rpc: "https://mainnet.infura.io/v3/YOUR_KEY"
  polygon_rpc: "https://polygon-rpc.com"
  timeout: 30

openai:
  api_key: "your-openai-key"
  model: "gpt-3.5-turbo"
  max_tokens: 1000

# Slither analysis
sentinelx run slither -p "{contract_path: 'contract.sol', format: 'json'}"

# Mythril analysis
sentinelx run mythril -p "{contract_path: 'contract.sol', timeout: 300}"

# CVSS scoring
sentinelx run cvss -p "{vector: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'}"

# Comprehensive pwn analysis
sentinelx run pwn-toolkit -p "{binary: './challenge'}"

# Buffer overflow exploitation
sentinelx run binary-pwn -p "{binary: './target', type: 'buffer_overflow'}"

# ROP chain generation
sentinelx run rop-exploit -p "{binary: './target', type: 'execve', target: '/bin/sh'}"

# Heap exploitation
sentinelx run heap-exploit -p "{binary: './heap_challenge', technique: 'fastbin_dup'}"

# Generate shellcode
sentinelx run shellcode -p "{arch: 'amd64', payload: '/bin/sh'}"

# Fuzzing
sentinelx run fuzzer -p "{target: 'http://example.com', iterations: 1000}"

# Static code analysis
sentinelx run web2-static -p "{target: 'app.php', language: 'php'}"

# Monitor blockchain
sentinelx run chain-monitor -p "{network: 'ethereum', addresses: ['0x123...']}"

# BNB Chain operations
sentinelx run bnb-chain -p "{operation: 'status'}"
sentinelx run bnb-chain -p "{operation: 'balance', address: '0x123...'}"
sentinelx run bnb-chain -p "{operation: 'token_info', token_address: '0xabc...'}"
sentinelx run bnb-chain -p "{operation: 'gas_tracker'}"

Workflows allow you to chain multiple security tasks together:

name: "comprehensive_audit"
description: "Complete security audit workflow"
continue_on_error: true

steps:
  - name: "contract_analysis"
    task: "slither"
    params:
      contract_path: "contract.sol"
  
  - name: "deep_analysis"
    task: "mythril"
    params:
      contract_path: "contract.sol"
      timeout: 300
    depends_on: ["contract_analysis"]
  
  - name: "vulnerability_scoring"
    task: "cvss"
    params:
      vector: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
    depends_on: ["deep_analysis"]

# Run all tests
pytest

# Run with coverage
pytest --cov=sentinelx

# Run specific test file
pytest tests/test_core.py

1. Create your task class:

from sentinelx.core.task import Task, register_task

@register_task("my-task")
class MyTask(Task):
    """Custom security task."""
    
    REQUIRED_PARAMS = ["target"]
    OPTIONAL_PARAMS = ["timeout"]
    
    async def execute(self, context, **kwargs):
        # Your task implementation
        return {"status": "completed", "data": result}

2. Register and test:

# Verify registration
sentinelx list | grep my-task

# Test your task
sentinelx run my-task -p "{target: 'test'}"

For detailed documentation, see the docs/ directory:

• User Guide - Complete user documentation and tutorials
• FAQ - Frequently asked questions and troubleshooting
• Task Reference - Complete task documentation and examples

• PWN Toolkit - Comprehensive binary exploitation documentation
• Social Engineering Toolkit - Complete social engineering framework documentation
• Lateral Movement Toolkit - Advanced network traversal and pivoting documentation
• Lateral Movement Toolkit - Advanced lateral movement with pwncat-cs integration

• Developer Guide - Development and plugin creation guide
• API Reference - Complete Python API documentation
• Advanced Features - Docker, performance, and reporting features
• Contributing Guide - How to contribute to SentinelX

• Examples Directory - Practical usage examples and tutorials
• Workflow Examples - Pre-built security assessment workflows
• Custom Task Examples - Complete task development examples

All Core Phases Complete! SentinelX is now a production-ready security framework with:

• 18+ Security Tasks across all major domains
• Complete Workflow Orchestration with dependency resolution
• Professional CLI Interface with rich formatting and interactive modes
• Plugin Architecture for easy extension
• Advanced Reporting and performance profiling
• Docker Integration for sandboxed execution
• Configuration Management with validation

• 🔒 Smart Contract Audit: Slither, Mythril, CVSS
• 💥 Exploit Development: Shellcode, Fuzzing, AutoPwn
• ⛓️ Blockchain Security: Chain monitoring, Transaction analysis
• 🎭 Red Team Operations: C2, Advanced lateral movement with pwncat-cs, Comprehensive social engineering campaigns
• 🔍 Digital Forensics: Memory, Disk, Blockchain IR
• 🤖 AI Security: LLM assistance, Prompt injection testing
• 🌐 Web Security: Static analysis, Vulnerability scanning

We welcome contributions! Please see our Contributing Guide for details.

# Clone repository
git clone https://github.com/your-org/sentinelx.git
cd sentinelx

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

This project is licensed under the MIT License - see the LICENSE file for details.

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

• Built with modern Python async/await patterns
• Uses Typer for CLI interface
• Styled with Rich for beautiful terminal output
• Powered by industry-standard security tools

SentinelX - Empowering security professionals with comprehensive, extensible, and professional security frameworks.

• MemoryForensics - Memory dump analysis
• DiskForensics - Disk image investigation
• ChainIR - Blockchain incident response

• LLMAssist - AI security analysis, code review, and threat modeling

All tasks include:

• ✅ Comprehensive parameter validation
• ✅ Professional error handling
• ✅ CLI integration with YAML/JSON output
• ✅ Real-world testing and validation
• ✅ Detailed logging and status reporting

# Smart contract security analysis
sentinelx run slither -p "{contract_path: MyToken.sol}"
sentinelx run cvss -p "{vector: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'}"

# Web application security
sentinelx run web2-static -p "{target: app.php, min_severity: medium}"
sentinelx run fuzzer -p "{target: 'http://example.com/login', type: sql, iterations: 50}"

# Blockchain monitoring
sentinelx run chain-monitor -p "{network: ethereum, type: network_status}"
sentinelx run chain-monitor -p "{network: ethereum, type: gas_tracker}"

# AI security analysis
sentinelx run llm-assist -p "{prompt: 'What is the OWASP Top 10?', type: security_question}"
sentinelx run llm-assist -p "{analyze_code: 'SELECT * FROM users WHERE id = ' + input, type: code_review}"

# Exploit development
sentinelx run shellcode -p "{type: sh, arch: x86_64, format: hex}"

SentinelX provides a unified interface to orchestrate specialized security tooling from a single command line interface, making it ideal for security professionals, penetration testers, and development teams.

Dependencies are listed in requirements.txt:

• typer
• rich
• pydantic
• slither-analyzer
• mythril
• angr
• pwntools
• scapy
• fastapi
• uvicorn[standard]
• graphviz
• PyYAML