Documentation — StaticCodeAudit Setup & CLI Guide

Getting Started

Requirements

Linux x86_64, macOS (Intel & Apple Silicon), or Windows x64. The binary is fully self-contained — no runtime, no dependencies to install.

Installation

Download the binary for your operating system from your account, place it in any folder, and make it executable.

# Extract the archive (or mount the .dmg on macOS)

$ tar -xzf staticcodeaudit-linux-x64.tar.gz

# Make the binary executable (Linux / macOS)

$ chmod +x ./staticcodeaudit-linux-x64

# Verify the binary

$ ./staticcodeaudit-linux-x64 --version

First Audit

Initialize a project, then run the audit. The --init flag generates an audit.config.json with auto-detected settings.

# Generate the project config (interactive)

$ ./staticcodeaudit-linux-x64 /path/to/your/project --init

# Run the audit

$ ./staticcodeaudit-linux-x64 /path/to/your/project

# Open the HTML report

$ open docs/audit-reports/SCA-REPORT-*.html

Configuration

All configuration is stored in audit.config.json at the root of your project. The --init flag generates this file with auto-detected settings. Two keys are mandatory.audit.config.json at the root of your project. The --init flag generates this file with auto-detected settings. Two keys are mandatory.

Mandatory Keys

Key	Description
languages	Array of languages to scan. Controls which detection rules are executed.
paths.include	Array of directories to scan (relative to project root).

Example Configuration

audit.config.json

{
  "languages": ["python", "javascript", "html"],
  "paths": {
    "include": ["src/", "app/", "lib/"],
    "exclude": ["node_modules/", "vendor/", ".venv/"]
  },
  "brand": {
    "tool_name": "StaticCodeAudit",
    "company_name": "CodeFixture",
    "prefix": "SCA",
    "logo": null
  },
  "reports": {
    "output_dir": "audit-reports",
    "history_dir": "audit-reports/audit-datas",
    "max_history": 10,
    "language": "en"
  },
  "categories": {
    "security":     { "enabled": true, "weight": 3 },
    "architecture": { "enabled": true, "weight": 2 },
    "ui":           { "enabled": true, "weight": 1 },
    "ux":           { "enabled": true, "weight": 1 },
    "maintenance":  { "enabled": true, "weight": 1 },
    "dependencies": { "enabled": false, "weight": 2 },
    "cicd":         { "enabled": false, "weight": 2 }
  },
  "retention": {
    "mode": null,
    "max_count": 10,
    "max_days": 90
  }
}

CLI Options

All flags are optional. The only required argument is the path to your project.

$ ./staticcodeaudit-linux-x64 /path/to/project [options]

Flag	Description
--init	Initialize a new project: register with UUID and generate audit.config.json.
--quick, -q	Fast mode: skip tests, fixture validation, and dependency scan.
--config, -c	Path to a custom config file (default: audit.config.json in project root).
--output, -o	Override the output directory for reports.
--project-name, -p	Override the project name displayed in the report.
--verbose, -v	Enable verbose console output with detailed progress.
--fail-on-high	Exit with code 1 if any HIGH severity finding is detected (useful for CI/CD).
--sarif	Generate a SARIF 2.1.0 export alongside the HTML report.
--sbom	Generate a CycloneDX 1.5 SBOM (Software Bill of Materials).
--git-blame	Resolve the author of each finding via git blame.
--skip-tests	Skip unit test execution.
--skip-deps	Skip dependency vulnerability scanning.
--skip-cicd	Skip CI/CD pipeline audit.
--script-lang	Console output language: en, fr, es, de (default: en).
--only-category	Run only a single category (e.g., --only-category security).
--disable-rule	Disable specific rules by key (repeatable).
--retention-dry-run	Preview which old reports would be deleted without actually removing them.
--self-test	Validate all fixtures (vulnerable + clean) against detection rules.
--install-hook	Install a git pre-commit hook that runs the audit automatically.
--list-rules	List all available detection rules and exit.
--list-categories	List all audit categories with their status and exit.
--list-projects	List all registered projects and exit.
--debug	Set debug level: info, detail, or trace.

Audit Categories

StaticCodeAudit organizes its 698 detection rules into 7 categories. Each category has a weight that influences the overall health score. Categories can be enabled or disabled in your configuration.

Category	Code	Weight	Default	Coverage
Security	SECURITY	3	✓	SQL injection, XSS, SSRF, path traversal, secrets, LDAP, cookies, crypto, GDPR
Architecture	ARCH	2	✓	Admin routes, DB in routers, direct queries, N+1, file size
UI	UI	1	✓	Inline styles, createElement, SVG inline, event listeners, DOM loops
UX	UX	1	✓	ARIA, alt text, focus, autoplay, i18n, console.log, WCAG 2.1
Maintenance	MAINTENANCE	1	✓	TODO/FIXME, deprecated APIs (5 languages), catch-all, debug statements
Dependencies	DEPENDENCIES	2	Disabled	CVE scan (pip-audit, npm audit), unpinned versions, license compliance
CI/CD	CICD	2	Disabled	GitHub Actions, GitLab CI, expression injection, permissions, unpinned actions

Dependencies and CI/CD are disabled by default. Enable them in audit.config.json. The weight influences the health score calculation: higher weight means the category has more impact.

Supported Languages

Declare the languages used in your project via the languages array in audit.config.json. Each language activates its dedicated set of detection rules.languages array in audit.config.json. Each language activates its dedicated set of detection rules.

Language	Config Value	File Extensions
Python	"python"	.py
JavaScript / TypeScript	"javascript"	.js, .jsx, .ts, .tsx, .mjs
HTML / Templates	"html"	.html, .htm, .xhtml, .vue, .svelte, .ejs, .hbs, .njk, .jinja, .jinja2, .twig, .liquid, .mustache, .phtml, .erb, .jsp, .asp, .aspx, .cshtml
Java	"java"	.java
C#	"csharp"	.cs
PHP	"php"	.php, .inc
YAML	"yaml"	.yml, .yaml

YAML scanning is used for CI/CD rules (GitHub Actions, GitLab CI). TypeScript is covered by the "javascript" config value — the same rules apply to both.

Output Formats

Every audit generates an HTML report and a JSON data file. Additional formats can be enabled via CLI flags.

HTML Report

Self-contained HTML file with CSS, JavaScript, and Chart.js inlined. Open in any browser, share by email, print to PDF. No server required.

SCA-REPORT-YYYY-MM-DD-HH-MM.html

JSON Data

Structured audit data for programmatic consumption and historical comparison. Contains all findings, scores, metadata, and statistics.

SCA-DATA-YYYY-MM-DD-HH-MM.json

SARIF 2.1.0

--sarif

OASIS standard for static analysis results. Compatible with GitHub Code Scanning, GitLab SAST, and Azure DevOps.

SCA-SARIF-YYYY-MM-DD-HH-MM.sarif

SBOM CycloneDX 1.5

--sbom

Software Bill of Materials listing every component and dependency in your project. Increasingly required by supply chain security regulations.

SCA-SBOM-YYYY-MM-DD-HH-MM.json

White-Label Branding

Customize reports with your own branding — free, no enterprise license required. All branding is configured in the brand section of audit.config.json.brand section of audit.config.json.

Option	Default	Effect
brand.tool_name	StaticCodeAudit	Displayed in report header, footer, console banner, and page title.
brand.company_name	CodeFixture	Displayed in report footer.
brand.prefix	SCA	File prefix for output files (e.g., SCA-REPORT-, SCA-DATA-).
brand.logo	null	Path to your logo (SVG, PNG, JPG). Replaces the default favicon and header icon in the report.
brand.primary_color	#1e3a5f	Start color of the report header gradient.
brand.accent_color	#2c5282	End color of the report header gradient.

audit.config.json

"brand": {
  "tool_name": "MyCompany Audit",
  "company_name": "MyCompany Inc.",
  "prefix": "MCA",
  "logo": "assets/my-logo.svg",
  "primary_color": "#1a1a2e",
  "accent_color": "#16213e"
}

Report Features

The HTML report is fully self-contained — a single file with all CSS, JavaScript, and charts inlined. No server, no external resources.

12+ Interactive Charts

Severity distribution, category breakdown, timing analysis, historical trends, confidence levels, and more. Powered by Chart.js (inlined).

Severity Grouping

Findings organized by severity (CRITICAL, HIGH, MEDIUM, LOW, INFO) with color-coded badges, file paths, line numbers, and code context.

Health Score

Logarithmic score (0-100) based on security findings, normalized by project size (LOC). Severity penalties: CRITICAL ×10, HIGH ×5, MEDIUM ×2, LOW ×1.

Git Blame Integration

When enabled (--git-blame), each finding displays the committer name, date, and commit hash for team accountability.

Baseline Comparison

Compare audit results against up to 10 previous snapshots (configurable). Track new, resolved, and persistent findings over time.

Report Retention

Auto-cleanup of old reports by count, age in days, or both. Use --retention-dry-run to preview deletions. Minimum 1 report always kept.

4-Language Reports

Full localization in English, French, Spanish, and German. Every string translated: rule names, risks, solutions, benefits, chart labels, glossary terms.

Built-in Glossary

36 acronyms and technical terms with tooltip preview. Every occurrence throughout the report is a clickable link to the glossary definition.

Executive Summary

At-a-glance dashboard at the top of every report: health score, severity breakdown, trend, and Priority Recommendations spanning the full width for immediate visibility.

4-Language User Guide

Every client delivery includes USER-GUIDE.md in English, French, Spanish, and German — covering CLI options, audit.config.json, report customization, suppression, and CI/CD integration.