Configuration

shadowaudit can be configured via a config file, CLI flags, or both. CLI flags always take precedence over config file values.

Config file discovery

shadowaudit uses cosmiconfig to find your config file. It searches for any of these, in order:

1. package.json — under a "shadowaudit" key
2. .shadowauditrc — JSON
3. .shadowauditrc.json
4. .shadowauditrc.yaml
5. .shadowauditrc.yml
6. .shadowauditrc.js
7. .shadowauditrc.cjs
8. .shadowaudit.yml
9. .shadowaudit.yaml
10. shadowaudit.config.js
11. shadowaudit.config.cjs

The first file found wins.

Config reference

Key	Type	Default	Description
spec	string	—	Path to OpenAPI 3.x or Swagger 2.0 spec file (.json, .yaml, or .yml). When omitted, delta comparison is skipped.
dir	string	process.cwd()	Directory to recursively scan for route definitions.
format	'table' | 'json' | 'sarif'	'table'	Output format. table is human-readable; json and sarif are machine-readable.
failOn	'critical' | 'high' | 'info'	'critical'	Exit code 1 when findings at or above this severity are present.
authPatterns	string[]	see defaults	Custom auth middleware names to detect. Checked in addition to hardcoded patterns.
ignore	string[]	['node_modules', 'dist', '.git', 'coverage']	Path segments to exclude from scanning.

Example: JSON config

{
  "spec": "./openapi.json",
  "dir": "./src",
  "format": "table",
  "failOn": "critical",
  "authPatterns": ["authAdminApi", "requireRole"],
  "ignore": ["node_modules", "dist", "tests"]
}

Example: YAML config

# .shadowauditrc.yml
spec: ./openapi.json
dir: ./src
format: table
failOn: critical
authPatterns:
  - authAdminApi
  - requireRole
ignore:
  - node_modules
  - dist
  - tests

CLI flag reference

Flag	Description	Default
--dir <path>	Directory to scan	Current directory
--spec <path>	Path to OpenAPI/Swagger spec	—
--format <type>	Output format: table, json, sarif	table
--fail-on <level>	Fail on: critical, high, info	critical
--framework <name>	Force framework: express, fastapi, django	Auto-detect
--config <path>	Path to config file	Auto-discovered

Flag override precedence

1. CLI flags (highest priority)
2. Config file values
3. Built-in defaults (lowest priority)

# CLI flag overrides config file
shadowaudit --format json --fail-on high
# → format: json, failOn: high (CLI wins)

Default auth patterns

These patterns are built into shadowaudit and always detected (you don't need to configure them):

Express.js / Node.js

.authenticate(       .authorize(          requireAuth           isAuthenticated
verifyToken           checkAuth            ensureLoggedIn        passport.authenticate
jwt.verify            bearerAuth           apiKeyAuth            basicAuth
auth(

FastAPI / Python

Depends(              Security(            oauth2_scheme         get_current_user
verify_token          HTTPBearer           HTTPBasic             APIKeyHeader
APIKeyQuery           require_auth         login_required        jwt_required
current_user

Django / Python

@login_required       @permission_required  IsAuthenticated       IsAdminUser
TokenAuthentication   SessionAuthentication  permission_classes   authentication_classes
LoginRequiredMixin    PermissionRequiredMixin jwt_required       requires_auth

Adding custom auth patterns

If your project uses a custom auth middleware with a non-standard name, add it to authPatterns:

authPatterns:
  - authAdminApi        # Ghost CMS pattern
  - authenticatePublic  # custom pattern
  - requireRole         # custom pattern

v0.3.0+ AST-based detection

In v0.3.0 and later, shadowaudit also uses AST-based detection that catches ANY middleware argument whose name contains auth, login, session, token, jwt, passport, permission, require, protect, secure, or verify (case-insensitive). This means custom middleware names like authAdminApi are often detected automatically without needing config.

ignore deep dive

The ignore field excludes files based on path segments, not globs. Any file whose path contains a segment from the ignore array is skipped.

Path	ignore: ['test']	Result
/api/test/users.js	test is a segment	Excluded
/api/contest/handlers.js	contest ≠ test	Included
/api/testimonials.js	testimonials ≠ test	Included

Test files are also automatically excluded regardless of ignore config.