Caspianignore

.caspianignore

When you click Ignore on an issue, the decision is persisted to a .caspianignore file in the workspace root. This file can be committed to version control so your entire team shares the same ignore list.

---

File Format

# Caspian Security Ignore File
# Format: RULE_CODE file/path.ts:line # optional reason

XSS001 src/app.ts:42 # False positive, sanitized upstream
CRED001 src/config.ts # Test credentials only
DB001 src/legacy/query.ts:107 # Parameterized at runtime via ORM

Syntax

Component	Required	Description
RULE_CODE	Yes	The rule code to ignore (e.g., XSS001, CRED001)
file/path.ts	Yes	Relative file path from workspace root
:line	No	Optional 1-based line number
# reason	No	Optional comment explaining why the issue is ignored

• Lines starting with # are comments
• Blank lines are skipped
• Paths use forward slashes (/)

---

How to Ignore an Issue

From the Results Panel

1. Click Ignore on any issue in the results table
2. An input box appears: "Reason for ignoring (optional)"
3. Enter a reason or press Enter to skip
4. The entry is appended to .caspianignore

From Diagnostics

1. Hover over a diagnostic squiggle
2. Click Quick Fix (Ctrl+.)
3. Select "Ignore Issue"

---

Matching Logic

When the scanner runs, each detected issue is checked against the ignore list:

1. Rule code must match -- XSS001 only ignores XSS001, not XSS002
2. File path must match -- relative path from workspace root
3. Line number (if specified) must match -- if the ignore entry includes :42, only line 42 is ignored
4. No line = entire file -- if no line number is specified, all instances of that rule in that file are ignored

Examples

Ignore Entry	What It Matches
XSS001 src/app.ts:42	Only XSS001 on line 42 of src/app.ts
CRED001 src/config.ts	All CRED001 issues anywhere in src/config.ts
DB001 src/legacy/query.ts:107	Only DB001 on line 107 of src/legacy/query.ts

---

Live Reloading

Caspian Security watches the .caspianignore file for changes:

• On startup: the file is loaded and cached
• On external change: a FileSystemWatcher detects edits and reloads the ignore list automatically
• On ignore click: the new entry is appended and the cache is updated

This means you can edit .caspianignore manually (e.g., in a text editor or during a code review) and the scanner picks up changes instantly without restarting VS Code.

---

Team Workflow

Since .caspianignore is a plain text file in the workspace root:

1. Commit it to version control -- git add .caspianignore
2. Review ignore entries in PRs -- treat them like code changes
3. Include reasons -- helps teammates understand why an issue was suppressed
4. Periodically audit -- remove entries for code that has been refactored or deleted

Recommended .gitignore

Do not add .caspianignore to .gitignore. The whole point is to share ignore decisions across the team.

---

Next Steps

• Confidence Scoring -- understand which issues are truly critical before ignoring
• FAQ -- troubleshooting and common questions