# StaticCodeAudit — User Guide

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [CLI Reference](#2-cli-reference)
3. [Project Configuration](#3-project-configuration-auditconfigjson)
4. [Customizing the Report](#4-customizing-the-report)
5. [Suppressing False Positives](#5-suppressing-false-positives)
6. [Custom Rules](#6-custom-rules)
7. [CI/CD Integration](#7-cicd-integration)
8. [Export Formats](#8-export-formats)

---

## 1. Quick Start

### First audit — no configuration required

```bash
./staticcodeaudit-windows-x64.exe /path/to/your/project
```

The report is written to `docs/audit-reports/` inside your project.
Open `SCA-REPORT-*.html` in any browser.

### Initialize a project config (recommended)

```bash
./staticcodeaudit-windows-x64.exe /path/to/your/project --init
```

This creates `audit.config.json` at the root of your project with all available
options pre-filled and commented. Edit it once, run audits indefinitely.

### Check your license

```bash
./staticcodeaudit-windows-x64.exe --license-info
```

---

## 2. CLI Reference

The binary name on your system includes the platform suffix
(e.g. `staticcodeaudit-windows-x64.exe`). All examples below use `./staticcodeaudit-windows-x64.exe`.

### Scan options

| Option | Description | Default |
|--------|-------------|---------|
| `project_path` | Path to the project to audit | `.` (current dir) |
| `--lang` | Report and console language: `fr`, `en`, `es`, `de` | `en` |
| `--version` | Print version and exit | — |
| `--license-info` | Display license status and exit | — |
| `--no-cache` | Disable rules compilation cache (force full rebuild) | off |
| `--no-incremental` | Disable incremental analysis (re-scan all files) | off |
| `--no-parallel` | Disable parallel scanning (force sequential) | off |

### Output options

| Option | Description |
|--------|-------------|
| `--fail-on-high` | Exit with code 1 if HIGH/CRITICAL findings exist (CI/CD gate) |
| `--sarif` | Generate a SARIF 2.1.0 file alongside the HTML report |
| `--sbom` | Generate a CycloneDX 1.5 SBOM (software bill of materials) |
| `--with-logs` | Save the console output to a `.log` file in the output directory |
| `--quiet` | Silent mode — only errors and the final result line are printed |

### Client features

| Option | Description |
|--------|-------------|
| `--init` | Create or edit `audit.config.json` interactively |
| `--create-rule` | Launch the wizard to write a custom rule |
| `--custom-rules-match` | Verify that every custom rule has its test fixtures |
| `--with-tests` | Auto-detect and run the project's unit tests |
| `--with-deps` | Run a dependency vulnerability scan (`pip-audit`, `npm audit`) |

### Common invocations

```bash
# Report in French
./staticcodeaudit-windows-x64.exe /path/to/project --lang=fr

# Audit + SARIF export (GitHub / GitLab integration)
./staticcodeaudit-windows-x64.exe /path/to/project --sarif

# Audit + dependency scan
./staticcodeaudit-windows-x64.exe /path/to/project --with-deps

# Audit + unit tests
./staticcodeaudit-windows-x64.exe /path/to/project --with-tests

# Silent mode for scripts
./staticcodeaudit-windows-x64.exe /path/to/project --quiet

# Fail CI pipeline on any HIGH or CRITICAL finding
./staticcodeaudit-windows-x64.exe /path/to/project --fail-on-high

# Full combination for CI
./staticcodeaudit-windows-x64.exe /path/to/project --sarif --fail-on-high --quiet --lang=en

# Save console output to a log file
./staticcodeaudit-windows-x64.exe /path/to/project --with-logs
```

---

## 3. Project Configuration (`audit.config.json`)

Place `audit.config.json` at the root of the project you want to audit.
Generate a pre-filled template with `--init`, or create it manually.

### Minimal example

```json
{
  "project": {
    "name": "My API",
    "version": "2.0"
  },
  "languages": ["python", "javascript"],
  "paths": {
    "include": ["src/", "api/"],
    "exclude": ["node_modules/", ".venv/", "*.min.js"]
  },
  "reports": {
    "output_dir": "docs/audit-reports",
    "language": "en"
  }
}
```

### Languages

Controls which rule sets are activated.

| Value | Scans |
|-------|-------|
| `python` | `.py` |
| `javascript` | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs` |
| `html` | `.html`, `.htm` |
| `java` | `.java` |
| `csharp` | `.cs` |
| `php` | `.php`, `.inc` |
| `yaml` | `.yml`, `.yaml` (CI/CD rules — enable the `cicd` category) |

### Paths

```json
"paths": {
  "include": ["src/", "app/", "lib/"],
  "exclude": [
    "node_modules/",
    "vendor/",
    ".venv/",
    "__pycache__/",
    "*.min.js",
    "dist/"
  ]
}
```

`include` lists folders to scan (relative to the project root).
`exclude` supports folder names, relative paths, and glob patterns (`*.min.js`).

### Categories

Each category can be enabled or disabled independently. `weight` controls
its contribution to the health score (1 = low, 5 = high).

```json
"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 }
}
```

Enable `dependencies` to run `pip-audit` / `npm audit` automatically.
Enable `cicd` to audit GitHub Actions / GitLab CI pipelines (requires `yaml`
in `languages`).

### Reports

```json
"reports": {
  "output_dir":   "docs/audit-reports",
  "history_dir":  "docs/audit-reports/audit-datas",
  "max_history":  10,
  "language":     "en"
}
```

`language` controls the report language independently of `--lang`
(the CLI flag takes precedence if both are set).
`max_history` is the number of past audits used to draw trend charts.

### Report retention

```json
"retention": {
  "mode":      "count",
  "max_count": 20,
  "max_days":  90
}
```

| `mode` | Behaviour |
|--------|-----------|
| `"count"` | Keep the `max_count` most recent reports |
| `"days"` | Delete reports older than `max_days` days |
| `"both"` | Apply both rules |
| `null` | No automatic deletion (default) |

### Thresholds

```json
"thresholds": {
  "max_high":       0,
  "max_medium":     10,
  "min_health":     80,
  "health_good":    90,
  "health_warning": 70
}
```

### Tests integration

```json
"tests": {
  "enabled":   true,
  "tests_dir": "tests/",
  "command":   "python -m pytest {tests_dir} -v --tb=short"
}
```

Activate with `--with-tests`. `{tests_dir}` is replaced at runtime.

---

## 4. Customizing the Report

### Branding

```json
"brand": {
  "tool_name":     "StaticCodeAudit",
  "company_name":  "Acme Corp",
  "prefix":        "SCA",
  "logo":          "assets/logo.svg",
  "primary_color": "#1e3a5f",
  "accent_color":  "#2c5282",
  "website_url":   "https://acme.example.com"
}
```

`logo` accepts a path relative to the project root or an absolute path.
Supported formats: SVG, PNG, JPG.

### Project header

```json
"project": {
  "name":        "Acme Backend",
  "version":     "3.1",
  "description": "REST API — payment processing service"
}
```

### Output directory

```json
"reports": {
  "output_dir": "docs/audit-reports"
}
```

The directory is created automatically. Reports are named
`SCA-REPORT-YYYY-MM-DD-HH-MM.html`.

---

## 5. Suppressing False Positives

### Method 1 — Inline comment

Add `# sca-ignore` at the end of the flagged line to suppress all rules on it:

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore
```

To suppress a specific rule only:

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore:weak_hash
```

Works in Python, JavaScript, TypeScript, Java, C#, PHP.

### Method 2 — Configuration file

```json
"rules": {
  "suppress": [
    {
      "rule": "weak_hash",
      "file": "src/legacy/auth.py",
      "reason": "MD5 used for non-security cache key only"
    },
    {
      "rule": "console.log",
      "file": "src/debug/logger.js"
    }
  ]
}
```

### Method 3 — Disabled rules (global)

```json
"rules": {
  "disabled": ["TODO/FIXME", "console.log", "hardcoded_secret"]
}
```

Rules in `disabled` never appear in any report. Use with caution.

---

## 6. Custom Rules

Write project-specific rules without modifying the built-in rule set.
Custom rules are stored in `custom-rules/` next to the binary and are
never overwritten by updates.

### Launch the wizard

```bash
./staticcodeaudit-windows-x64.exe /path/to/project --create-rule
```

The wizard guides you through: rule name, category, target language,
severity, detection pattern, descriptions in 4 languages, and fix examples.
Running `--create-rule` again on an existing rule opens it for editing.

### Verify custom rule coverage

```bash
./staticcodeaudit-windows-x64.exe /path/to/project --custom-rules-match
```

---

## 7. CI/CD Integration

### GitHub Actions

```yaml
- name: Static Code Audit
  run: |
    chmod +x ./staticcodeaudit-linux-x64
    ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  continue-on-error: false

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: docs/audit-reports/SCA-REPORT-*.sarif
```

### GitLab CI

```yaml
sca:
  script:
    - chmod +x ./staticcodeaudit-linux-x64
    - ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  artifacts:
    reports:
      sast: docs/audit-reports/SCA-REPORT-*.sarif
```

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | Audit passed |
| `1` | HIGH/CRITICAL findings detected (only with `--fail-on-high`) |
| `2` | Configuration error or missing required file |

---

## 8. Export Formats

### HTML (always generated)

Interactive report with charts, severity breakdown, trend history, and
per-finding remediation guidance. Open in any browser — no server needed.

Location: `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.html`

### SARIF 2.1.0

```bash
./staticcodeaudit-windows-x64.exe /path/to/project --sarif
```

Supported by GitHub Code Scanning, GitLab SAST, VS Code (SARIF Viewer),
Azure DevOps, SonarQube, and Checkmarx.

Location: `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.sarif`

### CycloneDX SBOM

```bash
./staticcodeaudit-windows-x64.exe /path/to/project --sbom
```

Software Bill of Materials in CycloneDX 1.5 JSON format. Lists all detected
dependencies with version information — useful for supply chain audits,
vulnerability disclosure compliance, and license inventory.

Location: `docs/audit-reports/SCA-SBOM-YYYY-MM-DD-HH-MM.json`

> SARIF and SBOM availability depends on your license tier.
> Contact support@codefixture.com for details.

---

*StaticCodeAudit by CodeFixture — Building Trust in Every Line.*
Support: support@codefixture.com
