ConsoleSentinel

Configuration

ConsoleSentinel works out of the box with zero configuration. For advanced control, create a consolesentinel.config.json file in your project root.

Minimal Config

{
  "url": "https://example.com",
  "maxPages": 50
}

Full Reference

{
  "url": "https://example.com",
  "maxPages": 100,
  "maxDepth": 5,
  "timeout": 30000,
  "viewport": { "width": 1440, "height": 900 },
  "userAgent": "ConsoleSentinel/3.0",
  "headers": {
    "Authorization": "Bearer ${CS_AUTH_TOKEN}"
  },
  "auditors": {
    "console": { "enabled": true, "severity": "high" },
    "network": { "enabled": true, "failOn4xx": true, "failOn5xx": true },
    "performance": { "enabled": true, "lcpThreshold": 2500, "clsThreshold": 0.1 },
    "seo": { "enabled": true },
    "security": { "enabled": true },
    "dast": { "enabled": true, "sqlInjection": true, "xss": true },
    "deepSeo": { "enabled": true },
    "visualAi": { "enabled": false, "baselineDir": "./baselines" },
    "accessibility": { "enabled": true, "standard": "WCAG2AA" },
    "crossPage": { "enabled": true },
    "assets": { "enabled": true, "maxBundleSize": 250000 }
  },
  "output": {
    "dir": "./consolesentinel-reports",
    "formats": ["json", "html", "markdown"],
    "openHtml": true
  },
  "ci": {
    "failOnGrade": "C",
    "failOnCritical": true,
    "failOnHighCount": 5
  },
  "exclude": [
    "/admin/**",
    "/api/**",
    "*.pdf"
  ],
  "include": [
    "/blog/**",
    "/products/**"
  ]
}

Config Fields

Top-Level

| Field | Type | Default | Description | | ----------- | -------- | ------- | ----------- | | url | string | — | Base URL to crawl (required) | | maxPages | number | 100 | Maximum pages to visit | | maxDepth | number | 5 | Maximum link depth from entry | | timeout | number | 30000 | Page navigation timeout (ms) | | viewport | object | 1440×900 | Browser viewport dimensions | | userAgent | string | Auto | Custom user-agent string | | headers | object | {} | Custom HTTP headers | | exclude | string[] | [] | Glob patterns to skip | | include | string[] | [] | Glob patterns to prioritize |

Auditors

Each auditor accepts enabled (boolean) plus module-specific options.

| Module | Key Options | | ------------- | ----------- | | console | severity — minimum severity to report | | network | failOn4xx, failOn5xx — treat status codes as findings | | performance | lcpThreshold, clsThreshold, fidThreshold | | seo | checkCanonical, checkStructuredData | | security | checkMixedContent, checkCsp | | dast | sqlInjection, xss, headerInjection, pathTraversal | | deepSeo | checkHreflang, checkSitemap, checkRobots | | visualAi | baselineDir, threshold, diffFormat | | accessibility | standard — WCAG2A, WCAG2AA, or WCAG2AAA | | crossPage | checkBrokenLinks, checkOrphans | | assets | maxBundleSize, checkSourceMaps |

Output

| Field | Type | Default | Description | | ---------- | ---------- | --------------------------- | ----------- | | dir | string | ./consolesentinel-reports | Report output directory | | formats | string[] | ["json", "html"] | Output format(s) | | openHtml | boolean | false | Auto-open HTML report |

CI / CD

| Field | Type | Default | Description | | ----------------- | --------- | ------- | ----------- | | failOnGrade | string | — | Exit non-zero if grade is at or below | | failOnCritical | boolean | true | Exit non-zero on any critical finding | | failOnHighCount | number | — | Fail if high-severity count exceeds threshold |

Environment Variables

Use ${VAR_NAME} syntax in string values to interpolate environment variables at runtime. Useful for tokens, auth headers, and secrets in CI.

{
  "headers": {
    "Authorization": "Bearer ${CS_AUTH_TOKEN}"
  }
}

Config Discovery

ConsoleSentinel looks for configuration in this order:

  1. --config <path> CLI flag
  2. consolesentinel.config.json in the current directory
  3. consolesentinel key in package.json
  4. Default settings (all auditors enabled, 100 max pages)

Next Steps