cognium-dev

cognium-dev

Static Application Security Testing CLI for detecting security vulnerabilities via taint tracking.

Installation

npm (recommended)

npm install -g cognium-dev

Standalone binary

Download from GitHub Releases.

Note: When using the standalone binary, place the wasm/ directory in the same location as the binary.

Quick Start

# Scan a single file
cognium-dev scan src/app.java

# Scan a directory
cognium-dev scan ./src

# Scan with specific language
cognium-dev scan api.py --language python

# Output as JSON
cognium-dev scan ./src --format json

# Show only critical vulnerabilities
cognium-dev scan ./src --severity critical

# Security findings only (skip quality/reliability passes)
cognium-dev scan ./src --category security

# Exclude specific CWEs (e.g. weak crypto noise)
cognium-dev scan ./src --exclude-cwe CWE-327,CWE-330

# Exclude test files
cognium-dev scan ./src --exclude-tests

# Software quality metrics
cognium-dev metrics ./src
cognium-dev metrics ./src --category complexity,coupling --format json

Commands

cognium-dev scan <path>

Scan files or directories for security vulnerabilities.

cognium-dev scan <path> [options]

Options:
  -l, --language <lang>      Force language (java|javascript|typescript|python|go|rust|bash|html)
  -f, --format <format>      Output format (text|json|sarif) [default: text]
  --threads <n>              Parallel analysis threads [default: 4]
  --severity <level>         Filter by severity:
                               - Single level: minimum severity (e.g., "high" shows high+critical)
                               - Multiple levels: exact match (e.g., "critical,high" shows only those)
                               - Valid levels: low, medium, high, critical
  --category <cats>          Filter by ISO 25010 category (comma-separated):
                               security, reliability, performance, maintainability, architecture
  --exclude-cwe <cwes>       Exclude specific CWEs (comma-separated, e.g. CWE-330,CWE-327)
  --exclude-tests            Exclude test files and directories
  -o, --output <file>        Write results to file
  -q, --quiet                Suppress progress output
  -v, --verbose              Show detailed output

Examples:

# Scan entire project
cognium-dev scan ./src

# Show only critical and high severity issues
cognium-dev scan ./src --severity critical,high

# Exclude test files and show only critical issues
cognium-dev scan ./src --exclude-tests --severity critical

# Security findings only (skip quality/reliability passes)
cognium-dev scan ./src --category security

# Reliability + performance findings only
cognium-dev scan ./src --category reliability,performance

# Exclude weak-crypto and weak-random findings
cognium-dev scan ./src --exclude-cwe CWE-327,CWE-330

# Generate SARIF report for CI/CD
cognium-dev scan ./src --format sarif --output results.sarif

# Scan with verbose output
cognium-dev scan ./src -v

# Quiet mode (no progress, only results)
cognium-dev scan ./src -q

cognium-dev init

Initialize a configuration file in your project.

cognium-dev init

Creates a cognium.config.json with customizable rules.

cognium-dev metrics <path>

Report software quality metrics for files or directories.

cognium-dev metrics <path> [options]

Options:
  -l, --language <lang>      Analyze only files for the given language
  -f, --format <format>      Output format (text|json) [default: text]
  --category <cats>          Filter metric categories (comma-separated):
                               complexity, size, coupling, inheritance,
                               cohesion, documentation, duplication
  --exclude-tests            Skip test files and directories
  -o, --output <file>        Write results to file
  -q, --quiet                Suppress per-file progress output

Examples:

# Show all metrics for a directory
cognium-dev metrics ./src

# Complexity and coupling metrics only
cognium-dev metrics ./src --category complexity,coupling

# JSON output for tooling integration
cognium-dev metrics ./src --format json --output metrics.json

# Java files only, skip tests
cognium-dev metrics ./src --language java --exclude-tests

Sample output:

src/UserController.java
  Complexity
    cyclomatic_complexity : 8.2
    WMC                   : 41
    halstead_volume       : 3820.4

  Size
    LOC                   : 182
    NLOC                  : 156
    function_count        : 9

  Coupling
    CBO                   : 6
    RFC                   : 22

  Composite Scores
    maintainability_index : 68.4 / 100
    code_quality_index    : 71.2 / 100
    bug_hotspot_score     : 32.1 / 100
    refactoring_roi       : 45.0 / 100

Available metrics: cyclomatic_complexity, WMC, halstead_volume, halstead_difficulty, halstead_effort, halstead_bugs, LOC, NLOC, comment_density, function_count, CBO, RFC, DIT, NOC, LCOM, doc_coverage, maintainability_index, code_quality_index, bug_hotspot_score, refactoring_roi.

cognium-dev version

Display version information.

cognium-dev version

Output Format

Cognium provides helpful, actionable output for each vulnerability found:

/path/to/VulnerableApp.java
  [!!!] sql_injection (Critical) [CWE-89]
      Line 45: sql_injection vulnerability: tainted data flows from line 42 to line 45
      User input is used in SQL query without sanitization
      → Fix: Use PreparedStatement with parameterized queries instead of string concatenation
  [!!] xss (High) [CWE-79]
      Line 78: xss vulnerability: tainted data flows from line 76 to line 78
      User input is rendered in HTML without proper encoding
      → Fix: Use HTML encoding/escaping functions before rendering user input in web pages

Found 2 vulnerability(ies) in 1 file(s)

Clean code = silent output: When no vulnerabilities are found, cognium stays quiet (Unix philosophy: no news is good news).

Use -v flag to see all scanned files including clean ones.

Output streams (stdout vs stderr)

cognium-dev follows the standard CLI convention: machine-readable payload on stdout, diagnostics on stderr.

Output	Stream	Notes
--format json document	stdout	Pure JSON starting at character 1. No banner, no preamble. Safe to pipe directly to jq, json_pp, etc.
--format sarif document	stdout	Pure SARIF 2.1.0 JSON. Same contract as --format json.
--format text report	stdout	The human-readable report (default).
Status lines (Loaded config: …, Suppressed N finding(s) …, Results written to …)	stderr
Spinner animation and final status (✔ Scanned N file(s))	stderr
Error messages and usage hints	stderr
Library log output (cross-file phase markers, budget warnings, etc.)	stderr	Silent by default; enable with --log-level <level> or COGNIUM_LOG_LEVEL.
Findings instrumentation (CIRCLE_IR_INSTRUMENT_FINDINGS=1)	stderr	JSONL [finding] … / [findings-summary] … lines.

The stdout contract for --format json and --format sarif is stable: pure parseable payload, version included inside the JSON object (not as a stdout preamble). Consumers can safely pipe stdout to a parser without skip-the-first-line idioms.

# Safe — stdout is pure JSON
cognium-dev scan ./src --format json | jq '.summary'

# Status lines and warnings on stderr, JSON on stdout
cognium-dev scan ./src --format json > results.json 2> scan.log

If you previously relied on a tail -n +2 or split("\n",1)[1] idiom against pre-3.89.2 builds, drop it — there is no longer a stdout banner to skip.

Detected Vulnerabilities

Type	CWE	Severity	Description
SQL Injection	CWE-89	Critical	User input in SQL queries
Command Injection	CWE-78	Critical	User input in system commands
Deserialization	CWE-502	Critical	Untrusted deserialization
XXE	CWE-611	Critical	XML external entity injection
Cross-Site Scripting (XSS)	CWE-79	High	User input in HTML output
Path Traversal	CWE-22	High	User input in file paths
SSRF	CWE-918	High	Server-side request forgery
LDAP Injection	CWE-90	High	User input in LDAP queries
XPath Injection	CWE-643	High	User input in XPath queries
NoSQL Injection	CWE-943	High	User input in NoSQL queries
Code Injection	CWE-94	Critical	Dynamic code execution
Open Redirect	CWE-601	Medium	User controls redirect destination
Log Injection	CWE-117	Medium	User input in logs
Trust Boundary	CWE-501	Medium	Data crosses trust boundary
External Taint Escape	CWE-20	Medium	External input reaches sensitive sink
Weak Random	CWE-330	Low	Weak random number generator
Weak Hash	CWE-327	Low	Weak hashing algorithm
Weak Crypto	CWE-327	Low	Weak cryptographic algorithm
Insecure Cookie	CWE-614	Low	Cookie without security flags

Code Quality Analysis

In addition to security vulnerabilities, cognium-dev scan runs 17 code quality passes and reports findings in five ISO 25010 categories:

Category	Rule IDs	Example Issues
Reliability	null-deref, resource-leak, unchecked-return, dead-code, variable-shadowing, leaked-global, unused-variable, infinite-loop, double-close, use-after-close, unhandled-exception, broad-catch, swallowed-exception, missing-guard-dom, cleanup-verify	Null pointer dereferences, unclosed streams, swallowed exceptions
Performance	n-plus-one, redundant-loop-computation, unbounded-collection, serial-await, react-inline-jsx	N+1 DB queries, unnecessary work inside loops
Maintainability	missing-public-doc, todo-in-prod, stale-doc-ref	Missing Javadoc/JSDoc, TODO comments in production code
Architecture	circular-dependency, orphan-module, dependency-fan-out, deep-inheritance, missing-override, unused-interface-method	Circular imports, overly deep class hierarchies

Quality findings appear alongside security findings in text output with their category tag:

src/UserService.java
  [!!] sql_injection (Critical) [CWE-89]
      ...
  [!] null-deref [reliability] (High) [CWE-476]
      Line 34: Return value of findById() is dereferenced without a null check
      → Fix: Check for null before dereferencing or use Optional<T>
  [i] missing-public-doc [maintainability] (Low)
      Line 12: Public method processRequest() has no Javadoc

Found 1 security finding(s) in 1 file(s)
Also found 2 code quality finding(s) in 1 file(s)

Exit codes: The CLI exits 1 only when security findings are present (so CI pipelines gate on vulnerabilities without being blocked by documentation or style findings). Quality-only scans exit 0.

Filter to security findings only: cognium-dev scan ./src --category security

Supported Languages

Language	Extensions	Frameworks
Java	.java	Spring, JAX-RS, Servlet
JavaScript	.js, .mjs	Express, Fastify, Node.js
TypeScript	.ts, .tsx	Express, Fastify, Node.js
Python	.py	Flask, Django, FastAPI
Go	.go	net/http, Gin, Echo, Fiber, Chi
Rust	.rs	Actix-web, Rocket, Axum
Bash	.sh, .bash	Shell scripts
HTML	.html, .htm	Web extraction preprocessor

Configuration

Create cognium.config.json in your project root:

{
  "include": ["src/**/*.java", "src/**/*.ts"],
  "exclude": ["**/test/**", "**/node_modules/**"],
  "severity": "medium",
  "rules": {
    "sql-injection": "error",
    "xss": "error",
    "command-injection": "error",
    "path-traversal": "warn"
  }
}

Severity Filtering

Cognium supports flexible severity filtering to focus on what matters:

Minimum Severity (Single Value)

Shows vulnerabilities at or above the specified level:

# Show only critical
cognium-dev scan ./src --severity critical

# Show high and critical
cognium-dev scan ./src --severity high

# Show medium, high, and critical
cognium-dev scan ./src --severity medium

Exact Severity Match (Comma-Separated)

Shows only the specified severity levels:

# Show only critical and high
cognium-dev scan ./src --severity critical,high

# Show only medium
cognium-dev scan ./src --severity medium

# Show low and medium
cognium-dev scan ./src --severity low,medium

CI/CD Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install cognium
        run: npm install -g cognium
      - name: Run security scan
        run: cognium-dev scan ./src --format sarif --output results.sarif --severity high
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI

security-scan:
  image: node:20
  script:
    - npm install -g cognium
    - cognium-dev scan ./src --format json --output gl-sast-report.json --severity high
  artifacts:
    reports:
      sast: gl-sast-report.json

Pre-commit Hook

Prevent commits with critical vulnerabilities:

#!/bin/sh
# .git/hooks/pre-commit

if ! cognium-dev scan . --severity critical --quiet; then
  echo "❌ Commit blocked: Critical security vulnerabilities found"
  exit 1
fi

Exit Codes

Code	Meaning
0	No security findings (quality-only findings do not trigger exit 1)
1	One or more security vulnerabilities found
2	Error during analysis

Use exit codes in CI/CD to fail builds when security vulnerabilities are detected:

# Fail build on any security finding
cognium-dev scan ./src || exit 1

# Fail build only on critical/high security findings
cognium-dev scan ./src --severity high || exit 1

# Fail build only on critical security findings
cognium-dev scan ./src --severity critical || exit 1

# Never fail on quality-only issues (always exit 0 for docs/style findings)
cognium-dev scan ./src --category reliability,performance,maintainability,architecture; echo "Quality scan done (exit $?)"

Performance

Cognium is built for speed:

• Parallel analysis: Process multiple files concurrently (configurable with --threads)
• Zero dependencies: Only one runtime dependency (circle-ir)
• Native performance: Powered by tree-sitter WASM parsers
• Lean binary: ~58MB standalone binary includes all dependencies

Architecture

• CLI: Lightweight wrapper with zero-dependency utilities
• Core Engine: circle-ir - High-performance SAST library
• Dependencies: Only 1 runtime dependency (circle-ir)

LLM Enhancement (Optional)

The core static analysis engine runs deterministically without any LLM. Optionally, you can enable LLM-based discovery modes for enhanced detection:

• Discovery Mode: LLM reads source code to locate vulnerable methods from scratch
• Verification Mode: Confirms whether static findings are actually exploitable
• Semantic Extraction: Extracts design intent for automated gap analysis

For details on LLM integration and benchmark improvements (42.5% → 78.3% on CWE-Bench with Claude Opus), visit cognium.net.

Benchmark Results

All scores below are from the static analysis engine — fully deterministic, no LLM required:

Benchmark	Score	Details
OWASP Benchmark	+100%	TPR 100%, FPR 0% (1415 test cases)
Juliet Test Suite	+100%	156/156 test cases, 9 CWEs
SecuriBench Micro	97.7% TPR	105/108 vulns detected, 6.7% FPR
CWE-Bench-Java	42.5%	51/120 real-world CVEs

Reproducing Benchmarks

The benchmark scores are verifiable and reproducible:

# Install cognium
npm install -g cognium

# Clone benchmark repositories
git clone https://github.com/OWASP-Benchmark/BenchmarkJava
git clone https://github.com/juliet-test-suite/juliet-test-suite-for-java
git clone https://github.com/CWE-Bench/cwe-bench-java

# Run scans
cognium-dev scan BenchmarkJava/src --format json -o owasp-results.json
cognium-dev scan juliet-test-suite-for-java --format json -o juliet-results.json
cognium-dev scan cwe-bench-java --format json -o cwe-bench-results.json

For detailed benchmark methodology and comparison with other tools, see cognium.dev.

Links

• GitHub
• circle-ir (Core Engine)
• Website

License

MIT