⚠️ Active Development Notice: Pentora is currently under active development and has not been released yet. APIs, CLI commands, and core features are subject to change. This project is not production-ready.

Pentora is a modular, high-performance security scanner that rapidly discovers network services, captures banners, and maps findings into vulnerability intelligence. Built with a powerful DAG-based execution engine, Pentora enables security teams to perform comprehensive network assessments with precision and efficiency.

• Lightning-fast scanning with intelligent rate limiting and concurrent execution
• DAG-based execution engine for parallel task processing and optimized workflows
• Adaptive host discovery using ICMP, ARP, and TCP probes
• Efficient resource management with configurable concurrency controls

• Modular service detection with extensible protocol parsers (SSH, HTTP, FTP, DNS, and more)
• Fingerprint-based asset profiling for accurate service version identification
• YAML plugin system with 19 embedded security checks and support for custom plugins
• Plugin-based vulnerability matching with CVE/CWE correlation and severity ratings
• Workspace management for organizing and querying scan results
• Hook system for custom automation and event-driven workflows

• Standalone CLI for quick ad-hoc scans and automation
• Server mode with REST/gRPC API for centralized scanning
• Web UI for interactive scan management and visualization (In Development)
• Cross-platform support (macOS, Linux, Windows)

• Network Discovery: Rapidly identify live hosts and services across large IP ranges
• Asset Inventory: Maintain accurate records of network infrastructure and services
• Vulnerability Assessment: Detect known vulnerabilities through banner analysis and CVE matching
• Security Monitoring: Continuous scanning for unauthorized services and configuration changes
• Penetration Testing: Reconnaissance and information gathering during security assessments

# Clone the repository
git clone https://github.com/pentora-ai/pentora.git
cd pentora

# Build the binary (outputs to dist/)
make binary

# Or build manually to dist/
mkdir -p dist
go build -o dist/pentora ./cmd

# Verify installation
./dist/pentora version

# Scan a single target with default ports (22,80,443)
pentora scan --targets 192.168.1.1

# Scan a CIDR range with custom ports
pentora scan --targets 192.168.1.0/24 --ports 21,22,80,443,8080

# Perform port discovery (scan ports 1-1000)
pentora scan --targets 192.168.1.1 --discover

# Enable vulnerability detection
pentora scan --targets 192.168.1.1 --vuln

# Scan with fingerprinting enabled
pentora scan --targets 10.0.0.0/24 --fingerprint

# List previous scan results
pentora storage list

# Get scan details
pentora storage get <scan-id>

# Start the Pentora server
pentora server start --addr 0.0.0.0 --port 8080

# Submit a scan via API
curl -X POST http://localhost:8080/api/v1/scans \
  -H "Content-Type: application/json" \
  -d '{"targets": ["192.168.1.0/24"], "ports": [22,80,443]}'

# Check scan status
pentora server status

Validate and manage DAG (Directed Acyclic Graph) definitions:

# Validate a DAG definition file
pentora dag validate scan-dag.yaml

# Export the internal scan DAG to YAML for inspection
pentora dag export --targets 192.168.1.0/24 --output scan.yaml

# Export with vulnerability evaluation enabled
pentora dag export --targets 10.0.0.1 --vuln --output full-scan.yaml

# Strict validation (treat warnings as errors)
pentora dag validate dag.yaml --strict

# Output validation results as JSON (for CI/CD)
pentora dag validate dag.yaml --json

19 essential security check plugins are embedded in the binary and ready to use immediately. Create custom vulnerability checks without writing Go code using YAML plugins:

# Load and evaluate YAML plugins
pentora scan --targets 192.168.1.1 --plugins ./my-plugins/

# List available plugins
pentora plugin list

# Validate a plugin definition
pentora plugin validate ssh-cve-check.yaml

Example YAML plugin (ssh-vuln-check.yaml):

name: SSH Vulnerability Check
version: 1.0.0
type: evaluation
author: security-team

metadata:
  cve: CVE-2024-XXXXX
  severity: high
  tags: [ssh, authentication, cve]

# Trigger when SSH version is detected
triggers:
  - data_key: ssh.version
    condition: exists
    value: true

# Match vulnerable versions
match:
  logic: AND
  rules:
    - field: ssh.version
      operator: version_lt
      value: "8.5"
    - field: ssh.banner
      operator: contains
      value: "OpenSSH"

output:
  vulnerability: true
  message: "SSH version vulnerable to authentication bypass"
  remediation: "Upgrade OpenSSH to version 8.5 or higher"

Supported Operators:

• String: equals, contains, startsWith, endsWith, matches (regex)
• Numeric: gt, gte, lt, lte, between
• Version: version_eq, version_lt, version_gt, version_lte, version_gte, version_between
• Logical: exists, in, notIn

Match Logic: AND, OR, NOT for combining rules

Embedded Plugins (19 total, ~50 KB):

• SSH (5): weak-key-exchange, weak-mac, weak-cipher, default-creds, regreSSHion (CVE-2024-6387)
• HTTP (4): missing-security-headers, server-version-disclosure, default-pages, weak-ssl
• TLS (4): weak-cipher, expired-cert, self-signed-cert, weak-protocol
• Database (3): mysql-default-creds, postgres-default-creds, redis-no-auth
• Network (3): open-telnet, open-ftp, weak-snmp-community

See pkg/plugin/testdata/plugins/ and pkg/plugin/embedded/ for examples.

pentora/
├── cmd/pentora/           # CLI entry point
├── pkg/
│   ├── api/              # REST and gRPC API servers
│   ├── appctx/           # Application context management
│   ├── cli/              # CLI command implementations
│   ├── config/           # Configuration loading and validation
│   ├── engine/           # DAG execution engine
│   ├── event/            # Event system for hooks and notifications
│   ├── fingerprint/      # Service fingerprinting engine
│   ├── hook/             # Hook system for custom automation
│   ├── logging/          # Structured logging utilities
│   ├── modules/          # Core scanning modules (discovery, probing, etc.)
│   ├── netutil/          # Network utilities and helpers
│   ├── parser/           # Protocol parsers (SSH, HTTP, FTP, etc.)
│   ├── plugin/           # YAML plugin system + legacy CVE matchers
│   ├── scan/             # Scan orchestration and coordination
│   ├── scanexec/         # Scan execution logic
│   ├── scanner/          # Port scanner and banner grabber
│   ├── server/           # HTTP/gRPC server implementation
│   ├── storage/         # Scan result persistence and queries
│   └── version/          # Version information
├── ui/                   # Web UI (React/TypeScript) - In Development
├── docs/                 # Documentation website (Docusaurus)
└── scripts/              # Build and packaging scripts

Pentora is built around several core concepts:

The DAG (Directed Acyclic Graph) engine orchestrates scan workflows by modeling dependencies between tasks. This enables:

• Parallel execution of independent tasks
• Automatic dependency resolution
• Efficient resource utilization
• Flexible workflow composition

Modules are self-contained units that perform specific scan phases:

• Discovery Module: Host discovery using multiple techniques
• Port Scanner Module: Fast TCP/UDP port scanning
• Banner Grabber Module: Service banner collection
• Fingerprint Module: Service version identification
• Vulnerability Module: CVE matching and risk assessment

All scan results are stored using the pkg/storage abstraction layer:

• LocalBackend (OSS): File-based JSONL storage with thread-safe operations
• OS-specific defaults: ~/Library/Application Support/Pentora (macOS), ~/.local/share/pentora (Linux)
• Features: filtering, pagination, partial updates, typed errors
• Retention policies: automatic cleanup based on age and count limits

Pentora uses a comprehensive testing approach:

• Run with make test or go test ./...
• Table-driven tests with testify/require
• Mock interfaces for isolation
• Target: >80% coverage for core packages

• Build tag: //go:build integration
• Run with make test-integration or go test -tags=integration ./...
• Black-box testing with real HTTP servers and network requests
• Examples:
  • pkg/server/app/app_integration_test.go - Server lifecycle testing
  • pkg/server/api/v1/plugins_integration_test.go - Plugin API endpoint testing
• Run all tests: make test-all

Before Every Commit (MANDATORY):

• ✅ make test - Unit tests only (fast, <2min)
• ✅ make validate - Linting, formatting, spell check, shell script validation

Before Opening PR (RECOMMENDED):

• ⚡ make test-all - Runs both unit AND integration tests

CI/CD Behavior:

• Unit tests run on every commit (fast feedback)
• Integration tests run on PR events (comprehensive validation)

Add support for new protocols:

package parser

func init() {
    Register("myprotocol", &MyProtocolParser{})
}

type MyProtocolParser struct{}

func (p *MyProtocolParser) Parse(banner string) (map[string]string, error) {
    // Parse banner and extract metadata
    return map[string]string{
        "service": "myservice",
        "version": "1.0.0",
    }, nil
}

Create vulnerability detection rules without writing Go code:

name: HTTP Vulnerable App Detection
version: 1.0.0
type: evaluation
author: security-team

metadata:
  cve: CVE-2024-XXXXX
  severity: high
  tags: [http, web, cve]

triggers:
  - data_key: http.server
    condition: exists
    value: true

match:
  logic: AND
  rules:
    - field: http.server
      operator: contains
      value: "VulnerableApp/1.0"
    - field: service.port
      operator: equals
      value: 8080

output:
  vulnerability: true
  message: "Vulnerable application detected"
  remediation: "Upgrade to version 2.0 or higher"

Benefits:

• ✅ No recompilation needed
• ✅ Easy to create and share
• ✅ Declarative and readable
• ✅ Supports complex matching logic

For advanced use cases, you can still create Go-based plugins:

package plugin

func init() {
    Register(&Plugins{
        ID:   "custom_vuln_check",
        Name: "Custom Vulnerability Check",
        RequirePorts: []int{8080},
        RequireKeys:  []string{"http/server"},
        MatchFunc: func(ctx map[string]string) *MatchResult {
            if strings.Contains(ctx["http/server"], "VulnerableApp/1.0") {
                return &MatchResult{
                    CVE:     []string{"CVE-2024-XXXXX"},
                    Summary: "Vulnerable application detected",
                }
            }
            return nil
        },
    })
}

React to scan events:

package main

import "github.com/pentora-ai/pentora/pkg/hook"

func init() {
    hook.Register("on_scan_complete", func(data interface{}) error {
        // Send notification, update database, etc.
        return nil
    })
}

For comprehensive documentation, visit:

• Documentation Site: https://docs.pentora.ai (In Development)
• Getting Started Guide: docs/getting-started/installation.md
• CLI Reference: docs/cli/overview.md
• Architecture Overview: docs/architecture/overview.md

We welcome contributions! Pentora is in active development, and we're building the foundation for a powerful security scanning platform.

Areas where we need help:

• Core scanning engine improvements
• Protocol parser implementations
• Vulnerability detection plugins
• Documentation and examples
• UI/UX design and implementation
• Testing and bug reports

Please read our contributing guidelines before submitting pull requests.

• Complete core scanning engine
• REST/gRPC API implementation
• Web UI for scan management
• Distributed scanning support
• Enhanced reporting capabilities
• Integration with popular security tools
• Cloud deployment guides
• First stable release (v1.0.0)

Licensed under the Apache License, Version 2.0. See LICENSE.md for details.

• Website: https://pentora.ai
• Documentation: https://docs.pentora.ai
• GitHub: https://github.com/pentora-ai/pentora
• Issues: https://github.com/pentora-ai/pentora/issues
• Discussions: https://github.com/pentora-ai/pentora/discussions

Note: Pentora is under active development. Star the repository to stay updated on releases and new features!