Shared — pr0t31n

How It Works

The Shared Libraries (/opt/pr0t31n/shared/) provide the foundational infrastructure that every pr0t31n tool builds on. Rather than each tool reimplementing output formatting, logging, tool execution wrappers, and schema validation independently, these shared modules enforce consistency across the entire toolkit. Tools import them directly from the shared path or vendor a copy into their own repository.

The core module is pr0t31n_schema.py — the universal output schema (v1.0/v1.1) that defines the canonical structure for meta.json, findings.json, and summary.json in every run directory. It provides constructors (make_meta(), make_finding(), make_summary()), validators, atomic writers, and the run-directory path builder that enforces the universal directory structure across all tools and platforms. Every finding produced by any tool passes through make_finding() to guarantee schema compliance.

pr0t31n_tool_runner.py is the universal execution wrapper. Every third-party binary invocation (nmap, nuclei, sslscan, etc.) routes through run_tool(), which automatically captures start/end times, exit codes, stdout/stderr, detects the tool's version, and emits a .log sibling file — a bash-session-style transcript providing complete audit trail for every external tool invocation. pr0t31n_event_log.py provides timestamped event logging at six levels (EVENT, INFO, WARN, ERROR, EXCEPTION, TOOL_ERROR) with dual-write to human-readable scan.log and machine-parseable scan.log.json.

Additional modules handle HTTP evidence recording (pr0t31n_http_evidence.py — request/response/log triplets for every Python HTTP request), false-positive management (pr0t31n_false_positives.py), findings catalogue validation (pr0t31n_catalogue.py), pause/resume support (pr0t31n_pause.py), threat intelligence lookups (pr0t31n_threat_intel.py), automatic Trawler invocation on pcap files (pr0t31n_trawler.py), and network topology mapping (pr0t31n_topology.py). All modules are stdlib-only with no third-party dependencies.

Security

Library module — no standalone execution or network access. _auth.py provides authentication for all Flask management apps: bcrypt password hashing (configurable work factor), secure session cookies (HttpOnly, SameSite=Lax, Secure), CSRF protection via Flask-WTF.

Features

Execution

pr0t31n_tool_runner.py

Universal subprocess wrapper — run_tool() replaces subprocess.run, auto-detecting tool versions, capturing stdout/stderr, timing execution, and emitting .log sibling files per Section 14.

pr0t31n_http_evidence.py

Attaches to a requests.Session to automatically record request/response/log triplets for every HTTP request issued by built-in Python code.

Integration

pr0t31n_trawler.py

Helper to auto-invoke Trawler on pcap files, extract top-talker targets, merge Trawler findings into the originating tool's findings.json, and emit .log siblings.

pr0t31n_pause.py

Pause/resume support — PauseManager checks for pause requests and gracefully halts tool execution at safe checkpoints, with EXIT_PAUSED exit code for process management.

Intelligence

pr0t31n_threat_intel.py

Threat intelligence lookups against curated blocklists for IP/URL reputation checking, used by Bastion, Trawler, and other analysis tools.

Logging

pr0t31n_event_log.py

Six-level timestamped event logger (EVENT/INFO/WARN/ERROR/EXCEPTION/TOOL_ERROR) with dual-write to scan.log and scan.log.json, plus automatic TOOL_ERROR detection from subprocess output.

Automatic Tool Error Detection

Per-tool regex libraries in the event log module detect error patterns in third-party tool output (nuclei [ERR], nmap 'Failed to resolve', etc.) and auto-emit TOOL_ERROR entries.

Quality

pr0t31n_false_positives.py

False-positive management — add, remove, load, and find FP records in the canonical falsePositives.json/csv format with backward compatibility for legacy false_positives.json.

pr0t31n_catalogue.py

Findings catalogue manager — validates catalogue entries against the 33-field schema, reports gap matrices, scaffolds missing entries, and merges per-tool catalogues into a master.

Schema

pr0t31n_schema.py

Universal output schema v1.0/v1.1 — constructors, validators, and atomic writers for meta.json, findings.json, and summary.json. Enforces the 15 required finding fields and 52 optional enrichment fields.

Universal Run Directory Builder

Constructs OS-aware run directories following the canonical path: <clients_base>/<client>/<year>/<tool>/<client>_<timestamp>/

pr0t31n_schema_compat.py

Compatibility layer for tools transitioning from legacy output formats to the universal schema.

Utility

pr0t31n_auth.py

Shared authentication module used by all Flask management apps — secret key generation, credential initialization, secure session cookies, and security headers.

pr0t31n_system_info.py

System information collection for meta.json population — hostname, OS, platform, architecture detection.

pr0t31n_topology.py

Network topology mapping and visualization helpers for cross-tool network intelligence.

pr0t31n_installer.py

Shared installer utilities for cross-platform dependency resolution across all tool install.py scripts.

pr0t31n_default_creds.py

Default credential database for authentication testing across multiple tools.

pr0t31n_dep_snapshot.py

Dependency snapshot utility for recording installed tool and library versions at scan time.

pr0t31n_proc_registry.py

Process registry for tracking spawned subprocesses across managed tool execution.

pr0t31n_timeouts.py

Centralized timeout configuration for consistent subprocess and network timeouts across all tools.

Use Cases

Consistent Output Across All Tools

Every tool in the toolkit produces identically structured output directories and findings files. When a new tool is created, importing pr0t31n_schema and calling make_finding() ensures immediate compatibility with Prometheus, Crucible, and all other consumers.

Complete Audit Trail

pr0t31n_tool_runner ensures that every nmap scan, nuclei run, or sslscan invocation produces a .log file capturing the exact command, tool version, timing, and full output — creating an unbroken audit chain from finding to evidence.

Cross-Tool Findings Correlation

Because all tools use the same schema with UUID-based finding IDs, catalogue IDs, and standardized risk levels, Prometheus and Phalanx can correlate findings across tools without tool-specific parsing logic.

Graceful Pause/Resume

During long-running scans, pr0t31n_pause enables operators to pause a tool cleanly via its management app (Crucible, Vantage), checkpoint its state, and resume later without losing progress.

CLI Reference

Output Files

File	Format	Description
`meta.json`	JSON	Tool identity and engagement metadata
`findings.json`	JSON	Universal findings array v1.1
`findings.csv`	CSV	CSV mirror of findings
`summary.json`	JSON	Aggregated statistics
`scan.log`	TXT	Human-readable timestamped log
`scan.log.json`	JSONL	Machine-readable JSON log events
`errors.log`	TXT	ERROR-level entries only

Invocation Methods

Method	Usage
CLI — Direct	`cd /opt/pr0t31n/Shared && python3 pr0t31n_schema.py` Run directly with command-line arguments.

Integration

Used By

All pr0t31n tools (shared modules)

Metadata

Name	Shared
Category	Utility
Version	1.7.1
Install Path	`/opt/pr0t31n/Shared`
Main File	`pr0t31n_schema.py`
GitHub	https://github.com/pr0t31n/shared.git