Running an Audit

The ges audit command is the core of GESF. It scans your actual source code with 8 independent scanners and produces actionable findings linked to compliance controls.

Basic Usage

ges audit

What Happens During an Audit

1. Walks your project directory (skipping node_modules, .git, dist, build, .ges)
2. Reads source files (up to 1MB each, all text-based languages)
3. Runs 8 scanners:
   • Secrets Scanner — Hardcoded passwords, API keys, tokens, private keys
   • Crypto Scanner — MD5, SHA1, weak encryption, disabled TLS (JavaScript, Python, Go, Java, Rust)
   • Code Security Scanner — SQL injection, XSS, eval/code injection (JavaScript, Python, Go, Rust)
   • Auth Scanner — Routes without auth, missing rate limiting, wildcard CORS
   • Config Scanner — Missing helmet/cors, .env secrets, Docker issues
   • Database Scanner — Missing audit columns, missing soft delete
   • IaC Scanner — Terraform/CloudFormation misconfigurations, open ports, public S3 (see IaC Scanner)
   • Dependency Analysis — Vulnerabilities, deprecated packages, license issues (see Dependency Analysis)
4. Deduplicates findings
5. Maps findings to compliance control IDs (e.g., GDPR-ART32-002)
6. Updates your compliance score in .ges/score.json

Example: Vulnerable Project

Given this source code:

src/config.js

DB_PASSWORD: process.env.DB_PASSWORD

src/auth.js

const crypto = require('crypto');
function hash(password) {
  return crypto.createHash('md5').update(password).digest('hex');
}

src/routes.js

app.get('/users', (req, res) => {
  db.query("SELECT * FROM users WHERE id = " + req.params.id);
});

Running ges audit produces:

  GESF Compliance Audit
  ────────────────────

  Scanning project files...
  Scanned 3 files

  ── Findings ─────────────────────

  Total findings: 4
  Critical: 3  High: 1  Medium: 0  Low: 0

  [SECRETS]
    [CRIT] Hardcoded password detected (src/config.js:1)
          DB_PASSWORD = "my-s..."

  [ENCRYPTION]
    [CRIT] MD5 hash algorithm detected (src/auth.js:3)

  [INJECTION]
    [CRIT] SQL injection via string concatenation (src/routes.js:2)

  [AUTHENTICATION]
    [HIGH] Route without auth middleware (src/routes.js:1)

  ── Compliance Score ──────────────
  GDPR ................ 42%
  OWASP ............... 55%
  Overall ............. 49%

Example: Clean Project

After fixing all issues:

src/config.js

const DB_PASSWORD = process.env.DB_PASSWORD;

src/auth.js

const argon2 = require('argon2');
async function hash(password) {
  return argon2.hash(password);
}

src/routes.js

app.get('/users', authenticate, (req, res) => {
  db.query("SELECT * FROM users WHERE id = $1", [req.params.id]);
});

Running ges audit again:

  GESF Compliance Audit
  ────────────────────

  Scanning project files...
  Scanned 3 files

  ── Findings ─────────────────────

  Total findings: 0
  Critical: 0  High: 0  Medium: 0  Low: 0

  ✓ No security or compliance issues found in source code.

  ── Compliance Score ──────────────
  GDPR ................ 72%
  OWASP ............... 65%
  Overall ............. 69%

CI Mode

Use --ci for CI/CD pipelines. Exits with code 1 if critical findings exist:

ges audit --ci
echo $?  # 1 if critical findings, 0 if clean

JSON Output

Use --json for machine-readable output:

ges audit --json

Returns a JSON object:

{
  "findings": [
    {
      "ruleId": "secrets-hardcoded-password",
      "severity": "critical",
      "category": "secrets",
      "title": "Hardcoded password detected",
      "file": "src/config.js",
      "line": 1,
      "evidence": "password = \"***masked***\"",
      "controlIds": ["GDPR-ART32-002"],
      "fix": "Use environment variables or a secrets manager"
    }
  ],
  "score": {
    "overall": 49,
    "frameworks": { "GDPR": { "score": 42 }, "OWASP": { "score": 55 } }
  }
}

Understanding Findings

Each finding contains:

Field	Description
title	Human-readable description of the issue
severity	critical, high, medium, or low
category	secrets, encryption, injection, xss, authentication, config, database, infrastructure, dependency
file	File path relative to project root
line	Line number where the issue was detected
evidence	The actual code snippet that triggered the finding (secrets are masked)
controlIds	Compliance control IDs this finding violates
fix	Suggested fix

Severity Levels

Severity	Meaning	Required Action
Critical	Immediate security risk	Must fix before deployment
High	Significant compliance gap	Should fix in current sprint
Medium	Notable concern	Should fix soon
Low	Minor improvement	Fix when convenient

Excluding Files with .gesignore

Create a .gesignore file in your project root to exclude specific files and directories from the audit. It uses the same syntax as .gitignore:

.gesignore

# Exclude test fixtures with intentional vulnerabilities
test/fixtures/
tests/

# Exclude generated code
generated/
*.generated.js

# Exclude vendor directories
vendor/
third-party/

# Exclude specific files
config/legacy.js

Pattern Types

Pattern	Matches
dir/	Entire directory and all contents
*.ext	All files with the extension
*pattern*	Wildcard matching
path/to/file	Specific file
# comment	Comment line (ignored)

The .gesignore file is useful for:

• Test fixtures that intentionally contain vulnerabilities
• Generated/vendored code you do not control
• Legacy code under separate remediation plans
• Third-party libraries bundled into your repo

Incremental Audit

For large projects, GESF supports incremental auditing — only re-scanning files that have changed since the last audit. This is used internally by the git hooks and auto-fix features for faster feedback.

The incremental audit:

1. Computes a hash of each file's content
2. Compares against the cached hash from the previous run
3. Only re-scans files whose hash has changed
4. Merges new findings with cached findings from unchanged files

This significantly reduces scan time for projects with many files where only a few change between commits.

Exercise: Audit a Real Project

1. Go to one of your existing projects (or use the vulnerable demo from Quick Start)
2. Run ges audit
3. Count the number of findings by severity
4. Pick the top 3 critical findings and fix them
5. Re-run ges audit and compare the output

Questions to ask yourself

• Which scanner found the most issues?
• Are there any findings you disagree with (false positives)?
• Which finding would be the most dangerous if exploited?

Exercise: Use .gesignore to Exclude False Positives

1. Using the project from the previous exercise, identify any false positives or test fixtures with intentional vulnerabilities
2. Create a .gesignore file:

echo "# Exclude test fixtures" > .gesignore
echo "test/fixtures/" >> .gesignore
echo "tests/" >> .gesignore

1. Re-run ges audit — the excluded files should no longer generate findings
2. Compare the finding count before and after

Questions

• How many findings were eliminated by the .gesignore file?
• When would it be inappropriate to use .gesignore to suppress findings?
• What is the risk of over-using .gesignore?

Exercise: Test Each Scanner Individually

Create a test file that triggers each scanner exactly once:

mkdir /tmp/scanner-test && cd /tmp/scanner-test
echo '{"name":"scanner-test"}' > package.json
ges init -n "Scanner Test" -t generic-web-application -f "GDPR,OWASP"

Trigger Secrets ScannerTrigger Crypto ScannerTrigger Code Security ScannerTrigger Auth ScannerTrigger Config ScannerTrigger Database Scanner

echo 'const apiKey = "sk-1234567890abcdef";' > src/secret.js

echo 'const hash = crypto.createHash("md5").update(data).digest("hex");' > src/crypto.js

echo 'db.query("SELECT * FROM users WHERE id = " + userId);' > src/sql.js

echo 'app.get("/api/data", handler);' > src/route.js

# Don't add .env to .gitignore and don't install helmet
echo 'DATABASE_URL=postgresql://admin:password@localhost/db' > .env

cat > src/model.js << 'EOF'
// Missing audit columns
const User = {
  id: { type: INTEGER, primaryKey: true },
  email: { type: STRING }
};
EOF

Now run ges audit — you should see 6 findings, one from each scanner category.

Exercise: Fix Findings and Track Score Improvement

1. Start with the vulnerable project from the Quick Start
2. Run ges audit and note your score (e.g., 49%)
3. Fix one category at a time:
   • First, fix all SECRETS findings → re-audit → note new score
   • Then fix all ENCRYPTION findings → re-audit → note new score
   • Then fix all INJECTION findings → re-audit → note new score
4. Plot your score improvement:

Fix Applied	Criticals Remaining	Score
None (baseline)	6	49%
Secrets fixed	3	55%
Crypto fixed	2	62%
Injection fixed	0	69%
Auth + Config fixed	0	78%