Technical Debt Tracking

Relevant source files

The following files were used as context for generating this wiki page:

• CHANGELOG.md
• SECURITY_REVIEW.md
• QUICK_START.md
• README.md
• configs/default.json
• CONTRIBUTING.md

Technical Debt Tracking is a specialized module within the Unified Security Scanner designed to identify and report infrastructure-level weaknesses that contribute to long-term maintenance and security risks. It specifically focuses on supply chain health, outdated dependencies, and End-of-Life (EOL) software components. By integrating these checks into the core scanning engine, the system provides a holistic view of a project's security posture beyond simple code-level vulnerabilities.

The module operates as a dedicated analyzer within the packages/core directory, coordinating with external package management tools to audit the project's dependency tree. It classifies findings into actionable categories such as outdated packages, insecure dependency versions, and maintenance risks like EOL status.

Sources: CHANGELOG.md:16-20, CONTRIBUTING.md:12-21, README.md:21-25

System Architecture

Technical Debt Tracking is implemented as a core analyzer within the packages/core/src/analyzers/ directory. It functions as part of the Multi-Tool Orchestration layer, working alongside traditional SAST and secrets detection tools.

The diagram above illustrates how the scan orchestrator triggers the Technical Debt Analyzer, which in turn invokes system-level commands to gather dependency data.

Sources: CONTRIBUTING.md:12-16, SECURITY_REVIEW.md:27-35, SECURITY_REVIEW.md:55-60

Key Components

Component	Responsibility
technical-debt.ts	The primary analyzer logic that manages command execution and finding generation.
npm audit Integration	Executes security audits against the local package.json to identify known vulnerabilities in the dependency tree.
npm outdated Integration	Checks for version drift between installed packages and the latest registry versions.
Results Parser	Normalizes JSON output from various package managers into the scanner's internal finding format.

Sources: SECURITY_REVIEW.md:27-60, CHANGELOG.md:16-20

Dependency Auditing Logic

The module leverages standard package manager CLI tools to perform deep-dives into the project's supply chain. It specifically monitors package.json and lock files to identify maintenance issues.

Outdated Package Detection

The scanner utilizes the npm outdated --json command to retrieve a structured list of dependencies that are behind their current or wanted versions. This process identifies potential "security bankruptcy" where a project falls too far behind to easily apply security patches.

const proc = spawn('npm', ['outdated', '--json'], {
  cwd: targetDir,
  shell: false, 
});

Sources: SECURITY_REVIEW.md:27-32, QUICK_START.md:144-150

End-of-Life (EOL) Detection

The analyzer specifically flags packages that have reached their End-of-Life, such as moment.js, which no longer receive security updates. These are typically categorized as HIGH severity findings due to the lack of future patching support.

Package	Detected Status	Severity
moment	EOL (End-of-Life)	🟠 HIGH
react < 18	Outdated	🟡 MEDIUM
lodash < 4	Prototype Pollution Risk	🟡 MEDIUM

Sources: QUICK_START.md:330-345, SECURITY_REVIEW.md:188-192

Security Implementation and Risk Management

While the Technical Debt module provides critical visibility, its implementation involves executing shell commands, which requires strict input validation and security controls.

Command Injection Prevention

A critical security review identified that early versions of the analyzer used shell: true when spawning npm processes. This created a CWE-78 (OS Command Injection) risk if the targetDir was user-controlled. The system has since been updated to use explicit validation and disable shell interpretation.

The sequence diagram shows the hardened flow for executing external dependency checks.

Sources: SECURITY_REVIEW.md:27-52, CHANGELOG.md:25-27

Path Traversal Mitigation

The module interacts extensively with the file system to locate package.json files. To prevent path traversal (CWE-22), the scanner uses path normalization (resolve, normalize) and strictly hardcodes relative file targets like package.json when joining paths with the user-provided scan target.

Sources: SECURITY_REVIEW.md:65-90, configs/default.json:20-30

Configuration and Customization

Technical debt tracking behavior can be tuned via the .securityrc.json configuration file. This allows teams to define what constitutes a "fail" condition for their specific project lifecycle.

Config Field	Type	Default	Description
scan.exclude	Array	["**/node_modules/**", "**/dist/**"]	Prevents the analyzer from scanning build artifacts.
severity.failOn	Array	["CRITICAL", "HIGH"]	Determines if outdated/EOL packages should block CI/CD.
performance.incrementalScan	Boolean	false	When enabled, only checks changed dependencies via git diff.

Sources: configs/default.json:17-50, QUICK_START.md:377-400

Summary of Findings

The Technical Debt Tracking system identifies three primary classes of issues:

1. Vulnerability Exposure: Known CVEs in current package versions identified via npm audit.
2. Version Lag: Significant drift from "latest" versions that complicates emergency patching.
3. Maintenance Risk: Usage of packages (like moment.js or lodash v3) that are unmaintained or have known structural security flaws.

Sources: QUICK_START.md:330-350, CHANGELOG.md:16-20