Security Posture Scanner - CLI Documentation

The Security Posture scanner checks structural security hygiene indicators—not a secrets scanner. It verifies that basic security best practices are in place: lockfile presence, .gitignore coverage, and npm audit results.

Important Limitations

This scanner focuses on structural hygiene, not secret detection:

What It Checks	What It Does NOT Check
Is `.env` in `.gitignore`?	Contents of `.env` files
Is lockfile present?	Actual vulnerabilities
Are `node_modules` ignored?	Source code patterns
`npm audit` severity summary	Deep vulnerability analysis

Note: For comprehensive security scanning, see the Security Scanners Scanner which detects installed tools like gitleaks, trivy, and semgrep.

Checks Performed

Lockfile Analysis

Check	Pass Criteria
Lockfile present	At least one lockfile found
Lockfile consistent	No drift between package.json and lockfile
Single lockfile	Not mixing npm + yarn + pnpm

.gitignore Coverage

Pattern	Must Be Ignored	Risk If Tracked
`node_modules/`	✅ Required	Bloated repo, dependency confusion
`.env`	✅ Required	Credential exposure
`.env.local`	✅ Required	Local credentials
`.pem`, `.key`	💡 Recommended	Private key exposure
`.vibgrate/scan_result.json`	💡 Recommended	Scan artifacts

Tracked Sensitive Files

Flags files that exist in git but should typically be ignored:

{
  "trackedSensitiveFiles": [
    {
      "path": ".env.production",
      "risk": "high",
      "recommendation": "Add to .gitignore and remove from git history"
    }
  ]
}

Warning: If sensitive files are tracked, add to .gitignore and use git filter-branch or BFG Repo-Cleaner to remove from history.

npm Audit Integration

If available, runs npm audit --json and summarizes:

{
  "auditSeverity": {
    "critical": 0,
    "high": 2,
    "moderate": 5,
    "low": 12,
    "total": 19
  }
}

Use Cases

Pre-Commit Validation

Ensure security posture before commits:

vg scan --format json | jq '.securityPosture'

CI Gate

Fail builds with security issues:

- name: Security Posture Check
  run: |
    CRITICAL=$(npx @vibgrate/cli scan --format json | jq '.securityPosture.auditSeverity.critical')
    if [ "$CRITICAL" -gt 0 ]; then
      echo "Critical vulnerabilities found"
      exit 1
    fi

Compliance Reporting

Generate security posture reports for auditors:

vg scan --format md > security-posture.md

Example Output

{
  "securityPosture": {
    "lockfile": {
      "present": true,
      "type": "pnpm-lock.yaml",
      "consistent": true
    },
    "gitignore": {
      "present": true,
      "coverage": {
        "nodeModules": true,
        "env": true,
        "envLocal": true,
        "privateKeys": true
      }
    },
    "trackedSensitiveFiles": [],
    "auditSeverity": {
      "critical": 0,
      "high": 2,
      "moderate": 5,
      "low": 12,
      "total": 19
    },
    "recommendations": [
      {
        "type": "audit",
        "severity": "high",
        "message": "Run npm audit fix to address 2 high severity vulnerabilities"
      }
    ]
  }
}