Docs/SOVA CLI

Technical

ARCHITECTURE

Understand how SOVA is built, how data flows through the system, and how to contribute new language parsers or security signal detectors.

MODULE DIAGRAM

CLI Layer

bin/sova.js → src/cli.ts

Interactive mode | sova scan (non-interactive)

calls

Library API

src/index.ts — scanProject(options)

Public interface: ScanOptions → SovaManifest

Scanner

src/scanner/

Directory walk + file dispatch

Signal Detector

src/security/signal-detector.ts

Routes files to detectors

uses

Parsers

src/parsers/

27 language parsers

Signal Detectors

src/security/signals/

10+ detection rules

produces

SovaManifest (JSON)

version, project, scan, applications

dependencyGraph, files, fileResults

securitySignals

DATA FLOW

CLI → Library API

The sova scan command (or interactive mode) resolves options and calls scanProject(options) from src/index.ts. The library API is intentionally stable and can be used programmatically.

Scanner → Parsers

src/scanner/ walks the project directory using glob patterns, identifies files by name, and dispatches each file to the appropriate parser via the ParserRegistry. Each parser returns a ParseResult with a dependency list and optional graph edges.

Scanner → Signal Detector

After parsing, each file's raw content is also passed to SignalDetector.detectAll(), which routes it to all registered ISignalDetector implementations for that language.

Manifest Assembly

The scanner aggregates all ParseResult objects and SecuritySignal arrays into a single SovaManifest object, de-duplicates dependencies, merges dependency graphs, and computes summary statistics.

Output

The CLI writes the manifest to disk as JSON. The library API returns it directly for programmatic use.

KEY DESIGN DECISIONS

Read-only, manifest-only scanning

SOVA explicitly filters for known manifest and lock file names. It never opens .js, .py, .ts, or any other source extension. This bounds the attack surface and makes the trust model clear.

Parser per language, not per file

Each parser handles all file types for its language (manifest + lock file). This keeps language-specific knowledge co-located and makes adding a new language a single-file operation.

"name_:_version" dependency format

Dependencies are stored as "package_:_version" strings rather than structured objects. This matches the format expected by the SecureNexus MetadataVulnerabilityBridge API directly, avoiding a transformation step.

Lazy parser loading

Parsers are loaded on demand via async factory functions in parser-registry.ts. This keeps startup time low when scanning projects that use only a subset of supported languages.

Signal detection is post-parse

Signal detectors receive raw file content, not the parsed dependency list. This allows detectors to find patterns (like obfuscated scripts in package.json) that wouldn't survive structured parsing.

FILE ORGANIZATION

src/

src/
  index.ts              ← Library API entry point (scanProject)
  cli.ts                ← CLI implementation
  types/
    manifest.ts         ← SovaManifest, FileEntry, FileResult types
    parser.ts           ← IParser interface, ParseResult type
  parsers/
    parser-registry.ts  ← Language → parser factory map
    base-parser.ts      ← Shared utilities for parsers
    *-parser.ts         ← One file per language
    _template/          ← Copy this to add a new parser
  scanner/
    index.ts            ← Directory walk + file dispatch
  security/
    types.ts            ← SecuritySignal, ISignalDetector, helpers
    signal-detector.ts  ← Aggregator: routes files to detectors
    signals/
      *-signals.ts      ← One file per language/ecosystem
      _template/        ← Copy this to add a new detector
  utils/
    version.ts          ← SOVA_VERSION constant
  cli/
    theme.ts            ← Terminal color/style helpers

Want to Contribute?

Contributing Guide

Development setup, PR process, DCO sign-off, adding parsers, and adding signal detectors.

Adding a Signal Detector

CLI Design System

Loading SOVA...