Skip to content

Runtime Policy Deep Dive

This page explains runtime control-plane policy in VulnParse-Pin: path/file policy (PFH), logging policy, and run context/service wiring.

Scope

Primary implementation files:

  • src/vulnparse_pin/app/bootstrap.py
  • src/vulnparse_pin/core/classes/dataclass.py
  • src/vulnparse_pin/io/pfhandler.py
  • src/vulnparse_pin/utils/logger.py
  • src/vulnparse_pin/cli/args.py

Runtime bootstrap sequence

initialize_runtime(args) assembles the runtime in this order:

  1. Resolve app paths (AppPaths.resolve(...)).
  2. Initialize bootstrap logger.
  3. Initialize PermFileHandler with root and symlink policy.
  4. Build initial RunContext.
  5. Ensure/load configs.
  6. Load scoring and TopN policy objects.
  7. Build FeedCacheManager and optional NVDFeedCache.
  8. Build immutable Services container.
  9. Rebind logger to run-specific log file.
  10. Build pass list (ScoringPass, TopNPass, SummaryPass).

Run context and services

RunContext is the runtime dependency object passed through parsing, enrichment, and pass execution.

RunContext fields:

  • paths
  • pfh
  • logger
  • services

Services fields:

  • feed_cache
  • nvd_cache
  • scoring_config
  • topn_config

RunContext and Services are frozen dataclasses to prevent accidental mutation after assembly.

PFH policy (PermFileHandler)

PFH centralizes path validation and safe file operations.

Policy controls

Constructor policy controls include:

  • allowed root set
  • forbid_symlinks_read
  • forbid_symlinks_write
  • enforce_roots_on_read
  • enforce_roots_on_write
  • file_mode (POSIX)
  • dir_mode (POSIX)

Typical enforcement

  • Read path: readable regular file and optional root confinement.
  • Write path: writable target and enforced root confinement by default.
  • Symlink handling: write symlinks forbidden by default.

Runtime diagnostics

--debug-path-policy prints policy (describe_policy()) and exits.

CLI flags for PFH/runtime security

Path policy flags are defined in cli/args.py:

  • --forbid-symlinks-read
  • --forbid-symlinks-write
  • --enforce-root-read
  • --enforce-root-write
  • --file-mode
  • --dir-mode
  • --debug-path-policy

These values are injected directly into PermFileHandler during bootstrap.

Logging policy (LoggerWrapper)

LoggerWrapper sets up two handlers:

  1. File handler at DEBUG level.
  2. Console handler at selected CLI log level.

Logging channels

  • vulnparse logger: console + file
  • vulnparse.fileonly logger: file only

Formats and labels

  • Console: colored level tags and icons.
  • File: timestamped plain text with ANSI stripped.
  • Label propagation through VulnParseRecordFilter (vp_label to label).

Custom level

A SUCCESS level (25) is registered between INFO and WARNING for status reporting.

Run log resolution

Run logs are generated by build_run_log(...) and created in paths.log_dir with timestamp-based names.

Bootstrap starts with bootstrap.log, then transitions to a run-specific log file after runtime context initialization.

Policy interactions

  1. PFH gates file-system access for cache, output, and log operations.
  2. Logger captures policy decisions and fallback behavior.
  3. RunContext ensures every subsystem receives the same policy instances.
  4. Services object controls policy consistency for pass and enrichment execution.

Operational tuning guidance

  • Keep --enforce-root-write enabled for production workloads.
  • Keep --forbid-symlinks-write enabled unless there is a controlled operational exception.
  • Increase log level from INFO to WARNING or ERROR for very large runs to reduce log overhead.
  • Use --debug-path-policy when validating deployment hardening before first production run.