qenex-pathfinder

A standalone Python security audit tool that scans codebases for vulnerabilities, misconfigurations, and dangerous patterns. Works as a CLI tool, a CI check, and an MCP server for Claude Code integration.

Features

• 60+ security checks across 12 categories (credentials, SQL injection,

command injection, XXE, CORS, network, crypto, systemd, permissions, async/sync, dependencies, Docker)

• AST-based analysis for Python files -- avoids false positives from comments

and docstrings

• Regex-based rules for config files, systemd units, Dockerfiles, and YAML
• Three output formats: colored text, JSON, SARIF 2.1.0 (GitHub Code

Scanning / VS Code compatible)

• MCP server for real-time scanning from Claude Code
• Configurable via .pathfinder.yml
• Zero mandatory dependencies beyond PyYAML (MCP is optional)

Installation

# From source
cd qenex-pathfinder
pip install .

# With MCP support
pip install .[mcp]

# Development
pip install .[dev]

CLI Usage

# Scan current directory
pathfinder .

# Scan a specific file
pathfinder /path/to/app.py

# Filter by severity
pathfinder . --severity high

# JSON output
pathfinder . --format json

# SARIF output (for CI)
pathfinder . --format sarif > results.sarif

# Run specific rules only
pathfinder . --rules PF-CRED-001,PF-SQLI-001

# Exclude paths
pathfinder . --exclude vendor/,test_data/

# Use custom config
pathfinder . --config /path/to/.pathfinder.yml

# Run as module
python -m pathfinder .

Exit Codes

| Code | Meaning | |------|-----------------------------------------------| | 0 | No findings at or above the requested severity | | 1 | One or more findings found |

MCP Server (Claude Code Integration)

Start the MCP server for interactive scanning from Claude Code:

pathfinder --mcp

Or add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "pathfinder": {
      "command": "pathfinder",
      "args": ["--mcp"]
    }
  }
}

MCP Tools

| Tool | Description | |---------------------|--------------------------------------| | scan_path | Scan a file or directory | | scan_file_content | Scan source code text directly | | list_rules | List all available security rules | | explain_finding | Get details about a specific rule ID |

Rule Reference

Credentials (PF-CRED-001 to PF-CRED-006, CWE-798)

| Rule ID | Title | Severity | Method | |-------------|--------------------------|----------|--------| | PF-CRED-001 | Private Key in Config | CRITICAL | Regex | | PF-CRED-002 | API Key in Source | HIGH | Regex | | PF-CRED-003 | Password Default Fallback| HIGH | AST | | PF-CRED-004 | Hardcoded JWT/Bearer | HIGH | Regex | | PF-CRED-005 | Cloud Provider Creds | CRITICAL | Regex | | PF-CRED-006 | SSH Private Key Content | CRITICAL | Regex |

SQL Injection (PF-SQLI-001 to PF-SQLI-004, CWE-89)

| Rule ID | Title | Severity | Method | |-------------|----------------------------------|----------|--------| | PF-SQLI-001 | f-string in SQL Execute | CRITICAL | AST | | PF-SQLI-002 | .format() in SQL Execute | CRITICAL | AST | | PF-SQLI-003 | String Concatenation in SQL | HIGH | AST | | PF-SQLI-004 | Subprocess sqlite3 Interpolation | HIGH | AST |

Command Injection (PF-CMDI-001 to PF-CMDI-005, CWE-78)

| Rule ID | Title | Severity | Method | |-------------|----------------------------------|----------|--------| | PF-CMDI-001 | shell=True with Variable | CRITICAL | AST | | PF-CMDI-002 | os.system() Call | HIGH | AST | | PF-CMDI-003 | os.popen() Call | HIGH | AST | | PF-CMDI-004 | eval() with User Input | HIGH | AST | | PF-CMDI-005 | exec() with User Input | HIGH | AST |

XXE and Deserialization (PF-XXE-001 to PF-XXE-005, CWE-611/502)

| Rule ID | Title | Severity | Method | |------------|---------------------------|----------|--------| | PF-XXE-001 | Unsafe xml.etree | MEDIUM | AST | | PF-XXE-002 | Unsafe xml.sax | MEDIUM | AST | | PF-XXE-003 | Unsafe lxml Parser | MEDIUM | AST | | PF-XXE-004 | Unsafe pickle | HIGH | AST | | PF-XXE-005 | Unsafe yaml.load() | HIGH | AST |

CORS (PF-CORS-001 to PF-CORS-003, CWE-942)

| Rule ID | Title | Severity | Method | |-------------|----------------------------|----------|--------| | PF-CORS-001 | CORS Allow All Origins | MEDIUM | AST | | PF-CORS-002 | CORS Header Wildcard | MEDIUM | Regex | | PF-CORS-003 | CORS Credentials Wildcard | HIGH | AST |

Network (PF-NET-001 to PF-NET-004, CWE-668)

| Rule ID | Title | Severity | Method | |------------|------------------------|----------|--------| | PF-NET-001 | Binding to 0.0.0.0 | MEDIUM | Regex | | PF-NET-002 | Binding to :: | MEDIUM | Regex | | PF-NET-003 | Debug Mode Enabled | MEDIUM | Regex | | PF-NET-004 | Dangerous Port Exposed | MEDIUM | Regex |

Cryptography (PF-CRYP-001 to PF-CRYP-005, CWE-327/328)

| Rule ID | Title | Severity | Method | |-------------|-------------------------|----------|--------| | PF-CRYP-001 | MD5 Hash Usage | MEDIUM | AST | | PF-CRYP-002 | SHA1 Hash Usage | MEDIUM | AST | | PF-CRYP-003 | DES/3DES Usage | HIGH | AST | | PF-CRYP-004 | Random for Crypto | HIGH | AST | | PF-CRYP-005 | Hardcoded Encryption Key| CRITICAL | Regex |

systemd (PF-SYSD-001 to PF-SYSD-005, CWE-522)

| Rule ID | Title | Severity | Method | |-------------|--------------------------------|----------|--------| | PF-SYSD-001 | Secret in Environment= | HIGH | Regex | | PF-SYSD-002 | Missing ProtectSystem | LOW | Text | | PF-SYSD-003 | Root Without Hardening | MEDIUM | Regex | | PF-SYSD-004 | World-Readable EnvironmentFile | HIGH | Stat | | PF-SYSD-005 | ExecStart with Elevated Privs | MEDIUM | Regex |

Permissions (PF-PERM-001 to PF-PERM-004, CWE-732)

| Rule ID | Title | Severity | Method | |-------------|------------------------------|----------|--------| | PF-PERM-001 | World-Writable File | HIGH | Stat | | PF-PERM-002 | Secret File Not 0600 | HIGH | Stat | | PF-PERM-003 | SUID/SGID on Script | CRITICAL | Stat | | PF-PERM-004 | Private Key World-Readable | CRITICAL | Stat |

Async/Sync (PF-ASYN-001 to PF-ASYN-005, CWE-834)

| Rule ID | Title | Severity | Method | |-------------|------------------------------|----------|--------| | PF-ASYN-001 | Sync Call in async def | MEDIUM | AST | | PF-ASYN-002 | Missing await on Coroutine | HIGH | AST | | PF-ASYN-003 | Blocking I/O in async def | LOW | AST | | PF-ASYN-004 | CPU-Bound in async def | LOW | AST | | PF-ASYN-005 | asyncio.sleep(0) Busy Loop | LOW | AST |

Dependencies (PF-DEP-001 to PF-DEP-003, CWE-1104)

| Rule ID | Title | Severity | Method | |------------|---------------------------|----------|--------| | PF-DEP-001 | Unpinned Dependency | LOW | Regex | | PF-DEP-002 | Unpinned Docker Image | MEDIUM | Regex | | PF-DEP-003 | Known Vulnerable Package | HIGH | Regex |

Docker (PF-DOCK-001 to PF-DOCK-008, CWE-250)

| Rule ID | Title | Severity | Method | |-------------|----------------------------|----------|--------| | PF-DOCK-001 | Container Running as Root | MEDIUM | Regex | | PF-DOCK-002 | Docker Socket Mounted | CRITICAL | Regex | | PF-DOCK-003 | Privileged Mode | CRITICAL | Regex | | PF-DOCK-004 | Missing no-new-privileges | LOW | Text | | PF-DOCK-005 | Host Network Mode | HIGH | Regex | | PF-DOCK-006 | Latest Tag Usage | LOW | Regex | | PF-DOCK-007 | Secrets in ENV/ARG | HIGH | Regex | | PF-DOCK-008 | No HEALTHCHECK | LOW | Regex |

SARIF Integration

SARIF output is compatible with:

• GitHub Code Scanning: Upload via github/codeql-action/upload-sarif
• VS Code: Install the SARIF Viewer extension
• Azure DevOps: Native SARIF support in pipelines

Example GitHub Actions workflow:

- name: Run Pathfinder
  run: pathfinder . --format sarif > pathfinder.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: pathfinder.sarif

Configuration

Create a .pathfinder.yml in your project root:

exclude_paths:
  - "vendor/"
  - "node_modules/"
  - ".venv/"
min_severity: low
exclude_rules: []
extensions:
  - ".py"
  - ".service"
  - ".yml"
  - ".yaml"
  - ".txt"
  - ".toml"

License

MIT -- Copyright (c) 2024 QENEX LTD