Reference Documentation

Shared Modules

Shared Python modules at /opt/pr0t31n/shared/ used across the toolkit.

/opt/pr0t31n/shared/pr0t31n_schema.py

Universal output structure builders and validators.

Function	Description
`make_meta(**kwargs)`	Build a meta.json dict with all required fields populated from kwargs + system info.
`write_meta(meta, run_dir)`	Write meta.json to the run directory.
`make_finding(**kwargs)`	Build a universal finding dict. Accepts all v1.0+v1.1 fields, defaults safely.
`append_finding(finding, findings_path)`	Append a finding to findings.json, creating the file if needed.
`write_universal_findings(findings, path)`	Write the complete findings.json array.
`augment_findings_file(path, tool, scope, phase)`	Fill id/tool/scope/phase on existing findings. Idempotent.
`universal_run_dir(client, tool, year, ts)`	Build the canonical run directory path.
`clients_base()`	Platform-aware clients base: /clients (Linux), /Users/Shared/clients (macOS), C:\clients (Win).
`to_relative_output_file(abs_path, run_dir)`	Convert absolute path to run-dir-relative. Validates no .. segments.
`make_summary(**kwargs)`	Build summary.json dict with statistics.
`write_summary(summary, run_dir)`	Write summary.json to the run directory.

/opt/pr0t31n/shared/pr0t31n_tool_runner.py

Subprocess wrapper that auto-emits .log sibling files for every third-party tool invocation.

Function	Description
`run_tool(cmd, *, output_file, timeout, tool_name, env, cwd)`	Drop-in subprocess.run replacement. Returns CompletedProcess. Auto-emits .log.
`write_tool_log(cmd, started, ended, exit_code, stdout, stderr, tool_name, tool_path, output_file)`	Low-level .log emitter for existing Popen patterns.
`get_tool_version(tool_name)`	Auto-detect tool version via _VERSION_FLAGS table.
`detect_tool_errors(tool, stdout, stderr)`	Per-tool regex library for extracting TOOL_ERROR entries from output.

/opt/pr0t31n/shared/pr0t31n_event_log.py

Timestamped event logging with parallel human-readable and JSON outputs.

Function	Description
`EventLogger(log_path, json_path)`	Logger class with .event(), .info(), .warn(), .error(), .tool_error(), .exception() methods.
`parse_dt_arg(s)`	Parse datetime-local string to datetime. Returns None on failure.
`filter_entries(entries, from_dt, to_dt)`	Filter log entries by time range (inclusive both ends).
`ERROR_LEVELS`	Set: {'ERROR', 'EXCEPTION', 'TOOL_ERROR', 'FATAL', 'CRITICAL'}

/opt/pr0t31n/shared/pr0t31n_catalogue.py

Findings catalogue management: validation, scaffolding, merging.

Function	Description
`report()`	Print gap matrix showing field completeness per tool catalogue.
`validate(catalogue_path)`	Validate field shapes against the 33-field schema.
`complete(tool, output)`	Upgrade existing entries + scaffold missing entries for a tool.
`merge(output)`	Merge all tool catalogues into master catalogue.

/opt/pr0t31n/shared/pr0t31n_http_evidence.py

Automatic HTTP request/response/log evidence capture for Python requests sessions.

Function	Description
`attach_http_evidence(session, run_dir, phase_getter)`	Register a response-hook on a requests.Session. Returns recorder object.
`recorder.last_paths()`	Return the (request, response, log) file paths from the last captured exchange.

/opt/pr0t31n/shared/pr0t31n_false_positives.py

False positive management: mark, recover, load, find.

Function	Description
`add_false_positive(project_dir, finding, csv_fieldnames)`	Remove finding from findings.json/csv, append to falsePositives.json/csv.
`remove_false_positive(project_dir, finding_id, csv_fieldnames)`	Reverse a false positive marking.
`load_false_positives(project_dir)`	Load FP list. Prefers falsePositives.json, falls back to legacy false_positives.json.
`find_false_positive(project_dir, finding_id)`	Find a single FP by ID.

/opt/pr0t31n/shared/pr0t31n_trawler.py

Automatic Trawler invocation for pcap producers.

Function	Description
`run_trawler_on_pcap(pcap_file, out_dir, targets, scope, findings_path, errors_log)`	Run Trawler on a pcap, merge findings into the originating tool's findings.json.

Per-tool vendored shim → /opt/pr0t31n/shared/pr0t31n_auth.py

Authentication, TLS, and security hardening for Flask apps. Each app keeps a thin _auth.py that calls configure() and re-exports.

Function	Description
`configure(app_dir, **kwargs)`	Bind file paths and auth-gate behaviour to the calling application.
`init_auth(app)`	Initialize auth on a Flask app: before_request gate, login/logout routes, session config.
`login_required(f)`	Decorator to require authentication on a route.
`generate_ssl_certs(app_dir)`	Generate self-signed TLS certificate and key.