guardrail-cli 1.0.6 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/README.md +483 -10
  2. package/dist/commands/baseline.d.ts +7 -0
  3. package/dist/commands/baseline.d.ts.map +1 -0
  4. package/dist/commands/baseline.js +79 -0
  5. package/dist/commands/baseline.js.map +1 -0
  6. package/dist/commands/cache.d.ts +13 -0
  7. package/dist/commands/cache.d.ts.map +1 -0
  8. package/dist/commands/cache.js +165 -0
  9. package/dist/commands/cache.js.map +1 -0
  10. package/dist/commands/evidence.d.ts +45 -0
  11. package/dist/commands/evidence.d.ts.map +1 -0
  12. package/dist/commands/evidence.js +197 -0
  13. package/dist/commands/evidence.js.map +1 -0
  14. package/dist/commands/index.d.ts +8 -0
  15. package/dist/commands/index.d.ts.map +1 -0
  16. package/dist/commands/index.js +15 -0
  17. package/dist/commands/index.js.map +1 -0
  18. package/dist/commands/scan-secrets.d.ts +47 -0
  19. package/dist/commands/scan-secrets.d.ts.map +1 -0
  20. package/dist/commands/scan-secrets.js +225 -0
  21. package/dist/commands/scan-secrets.js.map +1 -0
  22. package/dist/commands/scan-vulnerabilities-enhanced.d.ts +41 -0
  23. package/dist/commands/scan-vulnerabilities-enhanced.d.ts.map +1 -0
  24. package/dist/commands/scan-vulnerabilities-enhanced.js +368 -0
  25. package/dist/commands/scan-vulnerabilities-enhanced.js.map +1 -0
  26. package/dist/commands/scan-vulnerabilities-osv.d.ts +58 -0
  27. package/dist/commands/scan-vulnerabilities-osv.d.ts.map +1 -0
  28. package/dist/commands/scan-vulnerabilities-osv.js +716 -0
  29. package/dist/commands/scan-vulnerabilities-osv.js.map +1 -0
  30. package/dist/commands/scan-vulnerabilities.d.ts +32 -0
  31. package/dist/commands/scan-vulnerabilities.d.ts.map +1 -0
  32. package/dist/commands/scan-vulnerabilities.js +283 -0
  33. package/dist/commands/scan-vulnerabilities.js.map +1 -0
  34. package/dist/commands/secrets-allowlist.d.ts +7 -0
  35. package/dist/commands/secrets-allowlist.d.ts.map +1 -0
  36. package/dist/commands/secrets-allowlist.js +85 -0
  37. package/dist/commands/secrets-allowlist.js.map +1 -0
  38. package/dist/fix/applicator.d.ts +44 -0
  39. package/dist/fix/applicator.d.ts.map +1 -0
  40. package/dist/fix/applicator.js +144 -0
  41. package/dist/fix/applicator.js.map +1 -0
  42. package/dist/fix/backup.d.ts +38 -0
  43. package/dist/fix/backup.d.ts.map +1 -0
  44. package/dist/fix/backup.js +154 -0
  45. package/dist/fix/backup.js.map +1 -0
  46. package/dist/fix/engine.d.ts +55 -0
  47. package/dist/fix/engine.d.ts.map +1 -0
  48. package/dist/fix/engine.js +285 -0
  49. package/dist/fix/engine.js.map +1 -0
  50. package/dist/fix/index.d.ts +5 -0
  51. package/dist/fix/index.d.ts.map +1 -0
  52. package/dist/fix/index.js +12 -0
  53. package/dist/fix/index.js.map +1 -0
  54. package/dist/fix/interactive.d.ts +22 -0
  55. package/dist/fix/interactive.d.ts.map +1 -0
  56. package/dist/fix/interactive.js +172 -0
  57. package/dist/fix/interactive.js.map +1 -0
  58. package/dist/formatters/index.d.ts +6 -0
  59. package/dist/formatters/index.d.ts.map +1 -0
  60. package/dist/formatters/index.js +11 -0
  61. package/dist/formatters/index.js.map +1 -0
  62. package/dist/formatters/sarif-enhanced.d.ts +78 -0
  63. package/dist/formatters/sarif-enhanced.d.ts.map +1 -0
  64. package/dist/formatters/sarif-enhanced.js +144 -0
  65. package/dist/formatters/sarif-enhanced.js.map +1 -0
  66. package/dist/formatters/sarif-v2.d.ts +121 -0
  67. package/dist/formatters/sarif-v2.d.ts.map +1 -0
  68. package/dist/formatters/sarif-v2.js +356 -0
  69. package/dist/formatters/sarif-v2.js.map +1 -0
  70. package/dist/formatters/sarif.d.ts +72 -0
  71. package/dist/formatters/sarif.d.ts.map +1 -0
  72. package/dist/formatters/sarif.js +146 -0
  73. package/dist/formatters/sarif.js.map +1 -0
  74. package/dist/index.js +3362 -1397
  75. package/dist/index.js.map +1 -1
  76. package/dist/init/ci-generator.d.ts +18 -0
  77. package/dist/init/ci-generator.d.ts.map +1 -0
  78. package/dist/init/ci-generator.js +251 -0
  79. package/dist/init/ci-generator.js.map +1 -0
  80. package/dist/init/detect-framework.d.ts +15 -0
  81. package/dist/init/detect-framework.d.ts.map +1 -0
  82. package/dist/init/detect-framework.js +299 -0
  83. package/dist/init/detect-framework.js.map +1 -0
  84. package/dist/init/hooks-installer.d.ts +22 -0
  85. package/dist/init/hooks-installer.d.ts.map +1 -0
  86. package/dist/init/hooks-installer.js +302 -0
  87. package/dist/init/hooks-installer.js.map +1 -0
  88. package/dist/init/index.d.ts +8 -0
  89. package/dist/init/index.d.ts.map +1 -0
  90. package/dist/init/index.js +22 -0
  91. package/dist/init/index.js.map +1 -0
  92. package/dist/init/templates.d.ts +401 -0
  93. package/dist/init/templates.d.ts.map +1 -0
  94. package/dist/init/templates.js +240 -0
  95. package/dist/init/templates.js.map +1 -0
  96. package/dist/reality/reality-runner.d.ts +76 -0
  97. package/dist/reality/reality-runner.d.ts.map +1 -0
  98. package/dist/reality/reality-runner.js +454 -0
  99. package/dist/reality/reality-runner.js.map +1 -0
  100. package/dist/runtime/auth-utils.d.ts +43 -0
  101. package/dist/runtime/auth-utils.d.ts.map +1 -0
  102. package/dist/runtime/auth-utils.js +126 -0
  103. package/dist/runtime/auth-utils.js.map +1 -0
  104. package/dist/runtime/client.d.ts +74 -0
  105. package/dist/runtime/client.d.ts.map +1 -0
  106. package/dist/runtime/client.js +222 -0
  107. package/dist/runtime/client.js.map +1 -0
  108. package/dist/runtime/creds.d.ts +48 -0
  109. package/dist/runtime/creds.d.ts.map +1 -0
  110. package/dist/runtime/creds.js +245 -0
  111. package/dist/runtime/creds.js.map +1 -0
  112. package/dist/runtime/exit-codes.d.ts +47 -0
  113. package/dist/runtime/exit-codes.d.ts.map +1 -0
  114. package/dist/runtime/exit-codes.js +91 -0
  115. package/dist/runtime/exit-codes.js.map +1 -0
  116. package/dist/runtime/index.d.ts +9 -0
  117. package/dist/runtime/index.d.ts.map +1 -0
  118. package/dist/runtime/index.js +25 -0
  119. package/dist/runtime/index.js.map +1 -0
  120. package/dist/runtime/semver.d.ts +37 -0
  121. package/dist/runtime/semver.d.ts.map +1 -0
  122. package/dist/runtime/semver.js +110 -0
  123. package/dist/runtime/semver.js.map +1 -0
  124. package/dist/scanner/baseline.d.ts +52 -0
  125. package/dist/scanner/baseline.d.ts.map +1 -0
  126. package/dist/scanner/baseline.js +85 -0
  127. package/dist/scanner/baseline.js.map +1 -0
  128. package/dist/scanner/incremental.d.ts +30 -0
  129. package/dist/scanner/incremental.d.ts.map +1 -0
  130. package/dist/scanner/incremental.js +82 -0
  131. package/dist/scanner/incremental.js.map +1 -0
  132. package/dist/scanner/parallel.d.ts +43 -0
  133. package/dist/scanner/parallel.d.ts.map +1 -0
  134. package/dist/scanner/parallel.js +99 -0
  135. package/dist/scanner/parallel.js.map +1 -0
  136. package/dist/ui/frame.d.ts +68 -0
  137. package/dist/ui/frame.d.ts.map +1 -0
  138. package/dist/ui/frame.js +165 -0
  139. package/dist/ui/frame.js.map +1 -0
  140. package/dist/ui/index.d.ts +5 -0
  141. package/dist/ui/index.d.ts.map +1 -0
  142. package/dist/ui/index.js +16 -0
  143. package/dist/ui/index.js.map +1 -0
  144. package/package.json +42 -9
package/README.md CHANGED
@@ -5,14 +5,17 @@ The official command-line interface for Guardrail - AI-native code security and
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
- npm install -g @guardrail/cli
8
+ npm install -g guardrail-cli
9
9
  ```
10
10
 
11
11
  ## Quick Start
12
12
 
13
13
  ```bash
14
- # Authenticate
15
- guardrail auth --key gr_starter_your_api_key_here
14
+ # Authenticate with your API key
15
+ guardrail auth --key gr_pro_your_api_key_here
16
+
17
+ # Check authentication status (shows masked key)
18
+ guardrail auth --status
16
19
 
17
20
  # Scan your project
18
21
  guardrail scan --path ./your-project
@@ -21,27 +24,497 @@ guardrail scan --path ./your-project
21
24
  guardrail ship --path ./your-project
22
25
  ```
23
26
 
27
+ ## Authentication
28
+
29
+ The CLI uses enterprise-grade authentication with secure credential storage.
30
+
31
+ ### Commands
32
+
33
+ ```bash
34
+ # Authenticate with API key (validates against Guardrail API)
35
+ guardrail auth --key gr_pro_abc123xyz789
36
+
37
+ # Check current authentication status
38
+ # Shows masked key (gr_pro_****xyz9), tier, email, expiry
39
+ guardrail auth --status
40
+
41
+ # Force refresh cached entitlements
42
+ guardrail auth --refresh
43
+
44
+ # Logout and remove stored credentials
45
+ guardrail auth --logout
46
+ ```
47
+
48
+ ### Features
49
+
50
+ - **Real API Validation**: Keys are validated against `POST /v1/cli/auth/validate`
51
+ - **Secure Storage**: Credentials stored with 0600 permissions (Unix) or NTFS ACLs (Windows)
52
+ - **Local Caching**: Entitlements cached for 15 minutes to reduce API calls
53
+ - **Auto-Refresh**: Cache reused if > 5 minutes remaining; use `--refresh` to force
54
+ - **Key Masking**: API keys always displayed masked: `gr_pro_****abcd`
55
+ - **Expiry Warnings**: Yellow warning if entitlements expire within 72 hours
56
+
57
+ ### Credential Storage
58
+
59
+ | Platform | Location |
60
+ |----------|----------|
61
+ | macOS | `~/Library/Application Support/guardrail/state.json` |
62
+ | Linux | `~/.config/guardrail/state.json` |
63
+ | Windows | `%APPDATA%\guardrail\state.json` |
64
+
65
+ If `keytar` is available, sensitive tokens are stored in the OS keychain.
66
+
24
67
  ## Commands
25
68
 
26
69
  - `guardrail auth` - Authenticate with your API key
27
70
  - `guardrail scan` - Run security scans
28
- - `guardrail ship` - Ship readiness checks
29
- - `guardrail reality` - Browser testing for fake data
30
- - `guardrail smells` - Code smell analysis (Pro)
71
+ - `guardrail scan:secrets` - Scan for hardcoded secrets
72
+ - `guardrail scan:vulnerabilities` - Scan dependencies for CVEs (OSV integration)
73
+ - `guardrail scan:compliance` - Compliance assessment (Pro)
74
+ - `guardrail sbom:generate` - Generate SBOM (Pro)
75
+ - `guardrail ship` - Ship readiness checks (Starter+)
76
+ - `guardrail reality` - Browser testing for fake data (Starter+)
77
+ - `guardrail smells` - Code smell analysis
31
78
  - `guardrail fix` - Manual fix suggestions (Starter+)
79
+ - `guardrail autopilot` - AI-powered batch remediation (Pro)
80
+ - `guardrail cache:clear` - Clear OSV vulnerability cache
81
+ - `guardrail cache:status` - Show cache statistics
82
+ - `guardrail init` - Initialize Guardrail in a project (see [Init Command](#init-command))
83
+ - `guardrail menu` - Interactive menu
84
+
85
+ ## Init Command
86
+
87
+ The `guardrail init` command provides enterprise-grade project initialization with automatic framework detection and template-based configuration.
88
+
89
+ ### Basic Usage
90
+
91
+ ```bash
92
+ # Initialize with interactive prompts (auto-detects framework)
93
+ guardrail init
94
+
95
+ # Initialize with a specific template
96
+ guardrail init --template enterprise
97
+
98
+ # Initialize with CI and git hooks
99
+ guardrail init --ci --hooks
100
+
101
+ # Non-interactive mode
102
+ guardrail init --template startup --no-interactive
103
+ ```
104
+
105
+ ### Options
106
+
107
+ | Option | Description |
108
+ |--------|-------------|
109
+ | `-p, --path <path>` | Project path (default: `.`) |
110
+ | `-t, --template <template>` | Template: `startup`, `enterprise`, or `oss` |
111
+ | `--ci` | Generate CI/CD workflow (GitHub Actions with SARIF upload) |
112
+ | `--hooks` | Install git hooks (husky or lefthook) |
113
+ | `--hook-runner <runner>` | Specify hook runner: `husky` or `lefthook` |
114
+ | `--no-interactive` | Disable interactive prompts |
115
+
116
+ ### Framework Detection
117
+
118
+ Guardrail automatically detects your project framework by inspecting `package.json` and file structure:
119
+
120
+ | Framework | Detection Signals |
121
+ |-----------|-------------------|
122
+ | **Next.js** | `next` dependency, `next.config.*`, `app/` or `pages/` directory |
123
+ | **Express** | `express` dependency, `src/server.*` patterns, `routes/` directory |
124
+ | **NestJS** | `@nestjs/core` dependency, `nest-cli.json`, `*.module.ts` files |
125
+ | **Fastify** | `fastify` dependency, `@fastify/*` packages |
126
+ | **Remix** | `@remix-run/*` packages, `remix.config.*`, `app/routes/` |
127
+ | **Vite+React** | `vite` + `react` dependencies, `@vitejs/plugin-react` |
128
+
129
+ Based on the detected framework, Guardrail recommends the most relevant scans:
130
+
131
+ - **Next.js/Remix**: secrets, vulnerabilities, ship readiness, reality mode (auth flows)
132
+ - **Express/NestJS/Fastify**: secrets, vulnerabilities, ship readiness, compliance (logging/rate limits)
133
+ - **Vite+React**: secrets, vulnerabilities, ship readiness
134
+
135
+ ### Templates
136
+
137
+ Templates configure `.guardrail/config.json` with different defaults:
138
+
139
+ #### Startup Template
140
+ - **Use case**: Early-stage teams, fast iteration
141
+ - **Scan thresholds**: High (fewer alerts)
142
+ - **Compliance**: Disabled
143
+ - **Gating**: Block on critical only
144
+ - **Output**: Table format
145
+ - **Noise reduction**: Suppress test files, low-confidence findings
146
+
147
+ ```bash
148
+ guardrail init --template startup
149
+ ```
150
+
151
+ #### Enterprise Template
152
+ - **Use case**: Regulated industries, strict security requirements
153
+ - **Scan thresholds**: Low (catch everything)
154
+ - **Compliance**: Enabled (SOC2 by default)
155
+ - **Gating**: Block on critical and high, baseline/allowlist enabled
156
+ - **Output**: SARIF format with upload
157
+ - **SBOM**: Enabled
158
+
159
+ ```bash
160
+ guardrail init --template enterprise
161
+ ```
162
+
163
+ #### OSS Template
164
+ - **Use case**: Open source projects, contributor-friendly
165
+ - **Focus**: Supply chain security (SBOM, vulnerabilities)
166
+ - **Gating**: Permissive, baseline/allowlist enabled
167
+ - **Output**: Markdown format (PR-friendly)
168
+ - **Noise reduction**: Suppress test files, examples
169
+
170
+ ```bash
171
+ guardrail init --template oss
172
+ ```
173
+
174
+ ### Generated Files
175
+
176
+ #### Configuration (`.guardrail/config.json`)
177
+
178
+ ```json
179
+ {
180
+ "version": "1.0.0",
181
+ "template": "enterprise",
182
+ "framework": "nextjs",
183
+ "scans": {
184
+ "secrets": { "enabled": true, "threshold": "low" },
185
+ "vulnerabilities": { "enabled": true, "threshold": "medium" },
186
+ "compliance": { "enabled": true, "frameworks": ["soc2"] },
187
+ "sbom": { "enabled": true }
188
+ },
189
+ "gating": {
190
+ "enabled": true,
191
+ "blockOnCritical": true,
192
+ "blockOnHigh": true,
193
+ "baselineEnabled": true,
194
+ "allowlistEnabled": true
195
+ },
196
+ "output": {
197
+ "format": "sarif",
198
+ "sarifUpload": true,
199
+ "badgeGeneration": true
200
+ }
201
+ }
202
+ ```
203
+
204
+ #### CI Workflow (`.github/workflows/guardrail.yml`)
205
+
206
+ When using `--ci`, generates a GitHub Actions workflow that:
207
+ - Runs secrets and vulnerability scans
208
+ - Runs compliance checks (if enabled)
209
+ - Generates SBOM (if enabled)
210
+ - Uploads SARIF results to GitHub Security tab
211
+ - Runs ship readiness check
212
+ - Fails the workflow on critical/high findings
213
+
214
+ **Required**: Add `GUARDRAIL_API_KEY` to your repository secrets.
215
+
216
+ #### Git Hooks (`.husky/` or `lefthook.yml`)
217
+
218
+ When using `--hooks`, installs:
219
+ - **pre-commit**: Secrets scan on staged files
220
+ - **pre-push**: Full secrets + vulnerability scan + ship check
221
+
222
+ ### Examples
223
+
224
+ ```bash
225
+ # Next.js project with enterprise security
226
+ guardrail init --template enterprise --ci --hooks
227
+
228
+ # Express API with startup defaults
229
+ guardrail init --path ./api --template startup
230
+
231
+ # OSS project with lefthook
232
+ guardrail init --template oss --hooks --hook-runner lefthook
233
+
234
+ # CI-only setup (no hooks)
235
+ guardrail init --template enterprise --ci --no-interactive
236
+ ```
237
+
238
+ ## Vulnerability Scanning (OSV Integration)
239
+
240
+ The `scan:vulnerabilities` command uses real-time data from the [Open Source Vulnerabilities (OSV)](https://osv.dev) database.
241
+
242
+ ### Features
243
+
244
+ - **Real-time OSV API queries** - Live vulnerability data from Google's OSV database
245
+ - **Multi-ecosystem support** - npm, PyPI, RubyGems, Go
246
+ - **Lockfile parsing** - package-lock.json, pnpm-lock.yaml, yarn.lock
247
+ - **24-hour caching** - Reduces API calls with local cache in `.guardrail/cache/osv.json`
248
+ - **CVSS scoring** - Severity levels with optional NVD enrichment
249
+ - **Remediation paths** - Upgrade suggestions with breaking change detection
250
+ - **SARIF output** - GitHub code scanning integration
251
+
252
+ ### Usage
253
+
254
+ ```bash
255
+ # Basic vulnerability scan
256
+ guardrail scan:vulnerabilities --path ./my-project
257
+
258
+ # Bypass cache for fresh data
259
+ guardrail scan:vulnerabilities --no-cache
260
+
261
+ # Enable NVD enrichment for CVSS scores (slower)
262
+ guardrail scan:vulnerabilities --nvd
263
+
264
+ # Output as SARIF for GitHub code scanning
265
+ guardrail scan:vulnerabilities --format sarif -o results.sarif
266
+
267
+ # Filter by ecosystem
268
+ guardrail scan:vulnerabilities --ecosystem npm
269
+
270
+ # Fail CI if critical vulnerabilities found
271
+ guardrail scan:vulnerabilities --fail-on-critical
272
+ ```
273
+
274
+ ### Options
275
+
276
+ | Option | Description |
277
+ |--------|-------------|
278
+ | `-p, --path <path>` | Project path to scan (default: `.`) |
279
+ | `-f, --format <format>` | Output format: `table`, `json`, `sarif` (default: `table`) |
280
+ | `-o, --output <file>` | Write report to file |
281
+ | `--no-cache` | Bypass 24h cache, fetch fresh data from OSV |
282
+ | `--nvd` | Enable NVD enrichment for CVSS scores (slower) |
283
+ | `--fail-on-critical` | Exit with error if critical vulnerabilities found |
284
+ | `--fail-on-high` | Exit with error if high+ vulnerabilities found |
285
+ | `--ecosystem <eco>` | Filter by ecosystem: `npm`, `PyPI`, `RubyGems`, `Go` |
286
+
287
+ ### Cache Management
288
+
289
+ Vulnerability data is cached for 24 hours in `.guardrail/cache/osv.json`.
290
+
291
+ ```bash
292
+ # View cache statistics
293
+ guardrail cache:status
294
+
295
+ # Clear the cache
296
+ guardrail cache:clear
297
+
298
+ # Clear global cache
299
+ guardrail cache:clear --global
300
+ ```
301
+
302
+ ### SARIF Output for GitHub
303
+
304
+ Generate SARIF v2.1.0 output for GitHub code scanning:
305
+
306
+ ```bash
307
+ # Generate SARIF report
308
+ guardrail scan:vulnerabilities --format sarif -o vuln-results.sarif
309
+
310
+ # In GitHub Actions workflow:
311
+ - name: Run Guardrail Vulnerability Scan
312
+ run: guardrail scan:vulnerabilities --format sarif -o results.sarif
313
+
314
+ - name: Upload SARIF to GitHub
315
+ uses: github/codeql-action/upload-sarif@v2
316
+ with:
317
+ sarif_file: results.sarif
318
+ ```
319
+
320
+ The SARIF output includes:
321
+ - Rule metadata with CVE/GHSA IDs
322
+ - CVSS scores and vectors
323
+ - Remediation suggestions
324
+ - Package.json line locations
325
+ - Direct vs transitive classification
326
+
327
+ ### Consistent Command Headers
328
+
329
+ All analysis commands (`scan`, `ship`, `smells`, etc.) display a consistent framed header with:
330
+ - **Title**: Command name with icon
331
+ - **Project**: Project name from directory
332
+ - **Path**: Project path (truncated for long paths)
333
+ - **Started**: Timestamp when command started
334
+ - **Mode**: Tier badge when authenticated (FREE/STARTER/PRO/ENTERPRISE)
335
+ - **Metadata**: Command-specific options (e.g., scan type, severity filter)
336
+
337
+ The header respects `NO_COLOR` environment variable and `--no-color` flag for CI/accessibility.
32
338
 
33
339
  ## Tiers
34
340
 
35
341
  - **Free**: Basic scanning and validation
36
342
  - **Starter** ($29/mo): Ship checks, reality mode, fix suggestions
37
- - **Pro** ($99/mo): Advanced analysis, autopilot, smells detection
343
+ - **Pro** ($99/mo): Advanced analysis, autopilot, smells detection, compliance
38
344
  - **Enterprise** ($499/mo): Custom policies, SSO, dedicated support
39
345
 
346
+ ## Environment Variables
347
+
348
+ | Variable | Description |
349
+ |----------|-------------|
350
+ | `GUARDRAIL_API_BASE_URL` | Override API endpoint (default: `https://api.guardrail.dev`) |
351
+ | `GUARDRAIL_NO_INTERACTIVE` | Disable interactive prompts (`1` to disable) |
352
+ | `GUARDRAIL_NO_UNICODE` | Disable Unicode output (`1` for ASCII-only) |
353
+
354
+ ## Reality Mode
355
+
356
+ Reality Mode detects fake data, mock backends, and placeholder content in your running application using Playwright browser automation.
357
+
358
+ ### Generate Only (default)
359
+
360
+ ```bash
361
+ # Generate a Playwright test for the auth flow
362
+ guardrail reality --flow auth
363
+
364
+ # Generate test for a custom URL
365
+ guardrail reality --url http://localhost:8080 --flow checkout
366
+ ```
367
+
368
+ ### Generate + Run
369
+
370
+ ```bash
371
+ # Generate and immediately execute the test
372
+ guardrail reality --run --flow auth
373
+
374
+ # Run in headed mode (show browser)
375
+ guardrail reality --run --flow auth --headless=false
376
+
377
+ # Custom timeout and workers
378
+ guardrail reality --run --timeout 60 --workers 2
379
+
380
+ # Use HTML reporter for detailed results
381
+ guardrail reality --run --reporter html,list
382
+
383
+ # Full configuration example
384
+ guardrail reality --run \
385
+ --url http://localhost:8080 \
386
+ --flow checkout \
387
+ --timeout 45 \
388
+ --workers 4 \
389
+ --reporter html,json \
390
+ --trace retain-on-failure \
391
+ --video retain-on-failure \
392
+ --screenshot only-on-failure
393
+ ```
394
+
395
+ **Exit Code**: Mirrors Playwright's exit code (0 = pass, non-zero = fail)
396
+
397
+ #### 3. Record Mode
398
+
399
+ Opens Playwright in interactive recording mode using `codegen` to capture user actions.
400
+
401
+ ```bash
402
+ # Start recording session
403
+ guardrail reality --record --url http://localhost:3000
404
+
405
+ # Record with custom flow name
406
+ guardrail reality --record --url http://localhost:8080 --flow signup
407
+ ```
408
+
409
+ **How it works**:
410
+ 1. Opens browser with Playwright Inspector
411
+ 2. Interact with your app (click, type, navigate)
412
+ 3. Playwright records all actions with robust selectors
413
+ 4. Generated test saved to `.guardrail/reality/<runId>/reality-<flow>.test.ts`
414
+ 5. Press Ctrl+C when done
415
+
416
+ ### Options
417
+
418
+ | Flag | Description | Default |
419
+ |------|-------------|---------|
420
+ | `-p, --path <path>` | Project path | `.` |
421
+ | `-u, --url <url>` | Base URL of running app | `http://localhost:3000` |
422
+ | `-f, --flow <flow>` | Flow to test: auth, checkout, dashboard | `auth` |
423
+ | `-t, --timeout <seconds>` | Test timeout in seconds | `30` |
424
+ | `--headless` | Run in headless mode | `false` |
425
+ | `--run` | Execute the generated test immediately | `false` |
426
+ | `--record` | Open Playwright codegen for recording | `false` |
427
+ | `--workers <n>` | Number of parallel workers | `1` |
428
+ | `--reporter <type>` | Test reporter: list, dot, html, json | `list` |
429
+ | `--trace <mode>` | Trace mode: on, off, retain-on-failure, on-first-retry | `retain-on-failure` |
430
+ | `--video <mode>` | Video mode: on, off, retain-on-failure, on-first-retry | `retain-on-failure` |
431
+ | `--screenshot <mode>` | Screenshot mode: on, off, only-on-failure | `only-on-failure` |
432
+
433
+ ### Artifacts
434
+
435
+ When using `--run`, artifacts are saved under `.guardrail/reality/<runId>/`:
436
+
437
+ ```
438
+ .guardrail/reality/auth-1704123456789-a1b2c3d4/
439
+ ├── reality-auth.test.ts # Generated test file
440
+ ├── output.log # Playwright console output
441
+ ├── result.json # Run result summary (success, exitCode, duration)
442
+ ├── run-metadata.json # Execution configuration
443
+ ├── screenshots/ # Failure screenshots (if --screenshot enabled)
444
+ │ ├── test-failed-1.png
445
+ │ └── test-failed-2.png
446
+ └── report/ # HTML report (if --reporter html)
447
+ └── index.html
448
+ ```
449
+
450
+ ### Viewing Results
451
+
452
+ **HTML Report** (if `--reporter html`):
453
+ ```bash
454
+ npx playwright show-report .guardrail/reality/<runId>/report
455
+ ```
456
+
457
+ **JSON Results**:
458
+ ```bash
459
+ cat .guardrail/reality/<runId>/result.json
460
+ ```
461
+
462
+ **Logs**:
463
+ ```bash
464
+ cat .guardrail/reality/<runId>/output.log
465
+ ```
466
+
467
+ ### Prerequisites
468
+
469
+ Reality Mode requires Playwright and browser binaries.
470
+
471
+ **Install Playwright**:
472
+ ```bash
473
+ npm install -D @playwright/test
474
+ npx playwright install
475
+ ```
476
+
477
+ The CLI automatically detects missing dependencies and provides exact install commands with exit code 2.
478
+
479
+ ### Exit Codes
480
+
481
+ | Code | Meaning |
482
+ |------|---------|
483
+ | 0 | Tests passed |
484
+ | 1 | Tests failed |
485
+ | 2 | Playwright or browsers not installed |
486
+
487
+ ### Examples
488
+
489
+ **Quick test in CI**:
490
+ ```bash
491
+ guardrail reality --run --flow auth --headless --timeout 30
492
+ ```
493
+
494
+ **Debug with full visibility**:
495
+ ```bash
496
+ guardrail reality --run --flow checkout \
497
+ --no-headless \
498
+ --trace on \
499
+ --video on \
500
+ --screenshot on
501
+ ```
502
+
503
+ **Record custom flow**:
504
+ ```bash
505
+ guardrail reality --record --url http://localhost:3000 --flow onboarding
506
+ ```
507
+
508
+ **Parallel execution**:
509
+ ```bash
510
+ guardrail reality --run --workers 4 --reporter html,json
511
+ ```
512
+
40
513
  ## Support
41
514
 
42
- - 📖 [Documentation](https://guardrail.dev/docs)
43
- - 💬 [Discord](https://discord.gg/guardrail)
44
- - 📧 [Support](mailto:support@guardrail.dev)
515
+ - [Documentation](https://guardrail.dev/docs)
516
+ - [Discord](https://discord.gg/guardrail)
517
+ - [Support](mailto:support@guardrail.dev)
45
518
 
46
519
  ## License
47
520
 
@@ -0,0 +1,7 @@
1
+ /**
2
+ * baseline command
3
+ * Generate and manage baseline files for suppressing known findings
4
+ */
5
+ import { Command } from 'commander';
6
+ export declare function registerBaselineCommand(program: Command, requireAuth: () => any, printLogo: () => void): void;
7
+ //# sourceMappingURL=baseline.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,IAAI,CAqE7G"}
@@ -0,0 +1,79 @@
1
+ "use strict";
2
+ /**
3
+ * baseline command
4
+ * Generate and manage baseline files for suppressing known findings
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.registerBaselineCommand = registerBaselineCommand;
8
+ const path_1 = require("path");
9
+ const baseline_1 = require("../scanner/baseline");
10
+ const scan_secrets_1 = require("./scan-secrets");
11
+ const scan_vulnerabilities_1 = require("./scan-vulnerabilities");
12
+ const c = {
13
+ bold: (s) => `\x1b[1m${s}\x1b[0m`,
14
+ dim: (s) => `\x1b[2m${s}\x1b[0m`,
15
+ success: (s) => `\x1b[32m${s}\x1b[0m`,
16
+ info: (s) => `\x1b[34m${s}\x1b[0m`,
17
+ };
18
+ function registerBaselineCommand(program, requireAuth, printLogo) {
19
+ program
20
+ .command('baseline')
21
+ .description('Generate baseline file to suppress known findings')
22
+ .option('-p, --path <path>', 'Project path to scan', '.')
23
+ .option('--write <file>', 'Write baseline to file', '.guardrail/baseline.json')
24
+ .option('-t, --type <type>', 'Scan type: all, secrets, vulnerabilities', 'all')
25
+ .action(async (opts) => {
26
+ requireAuth();
27
+ printLogo();
28
+ console.log(`\n${c.bold('📋 BASELINE GENERATION')}\n`);
29
+ const projectPath = (0, path_1.resolve)(opts.path);
30
+ const baselinePath = (0, path_1.resolve)(opts.write);
31
+ console.log(` ${c.dim('Project:')} ${projectPath}`);
32
+ console.log(` ${c.dim('Baseline:')} ${baselinePath}`);
33
+ console.log(` ${c.dim('Type:')} ${opts.type}\n`);
34
+ const allFindings = [];
35
+ if (opts.type === 'all' || opts.type === 'secrets') {
36
+ console.log(` ${c.info('→')} Scanning for secrets...`);
37
+ const secretsResult = await (0, scan_secrets_1.scanSecrets)(projectPath, {
38
+ path: projectPath,
39
+ format: 'json',
40
+ excludeTests: false,
41
+ failOnDetection: false,
42
+ evidence: false,
43
+ });
44
+ for (const finding of secretsResult.findings) {
45
+ allFindings.push({
46
+ type: finding.type,
47
+ category: 'secrets',
48
+ title: finding.type,
49
+ file: finding.file,
50
+ line: finding.line,
51
+ snippet: finding.match,
52
+ });
53
+ }
54
+ console.log(` ${c.success('✓')} Found ${secretsResult.findings.length} secrets\n`);
55
+ }
56
+ if (opts.type === 'all' || opts.type === 'vulnerabilities') {
57
+ console.log(` ${c.info('→')} Scanning for vulnerabilities...`);
58
+ const vulnResult = await (0, scan_vulnerabilities_1.scanVulnerabilities)(projectPath, {
59
+ format: 'json',
60
+ });
61
+ for (const finding of vulnResult.findings) {
62
+ allFindings.push({
63
+ category: 'vulnerability',
64
+ title: `${finding.cve}: ${finding.title}`,
65
+ file: 'package.json',
66
+ line: 1,
67
+ snippet: `${finding.package}@${finding.version}`,
68
+ });
69
+ }
70
+ console.log(` ${c.success('✓')} Found ${vulnResult.findings.length} vulnerabilities\n`);
71
+ }
72
+ baseline_1.BaselineManager.saveBaseline(baselinePath, allFindings);
73
+ console.log(`${c.success('✓')} ${c.bold('Baseline created successfully!')}`);
74
+ console.log(` ${c.dim('File:')} ${baselinePath}`);
75
+ console.log(` ${c.dim('Findings:')} ${allFindings.length}`);
76
+ console.log(`\n ${c.dim('Use')} ${c.bold(`--baseline ${baselinePath}`)} ${c.dim('with scan commands to suppress these findings.')}\n`);
77
+ });
78
+ }
79
+ //# sourceMappingURL=baseline.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../src/commands/baseline.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Cache management commands
3
+ *
4
+ * Commands:
5
+ * - cache:clear - Clear the OSV vulnerability cache
6
+ * - cache:status - Show cache statistics
7
+ */
8
+ import { Command } from 'commander';
9
+ /**
10
+ * Register cache commands
11
+ */
12
+ export declare function registerCacheCommands(program: Command, printLogo: () => void): void;
13
+ //# sourceMappingURL=cache.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/commands/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2FpC;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,IAAI,GACpB,IAAI,CAiFN"}