Troubleshooting

This page covers common issues you might encounter when using SentriFlow and how to resolve them.

Installation Issues

Command Not Found

If you see sentriflow: command not found after installation:

For npm global install:


# Check if npm global bin is in PATH
npm config get prefix
# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"

For local install:


# Use npx to run
npx sentriflow router.conf
 
# Or use node_modules directly
./node_modules/.bin/sentriflow router.conf

Permission Errors


# macOS/Linux: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
 
# Or use a Node version manager like nvm

Validation Issues

”No Rules Matched”

If SentriFlow reports no issues but you expected some:


# List active rules to see what's loaded
sentriflow --list-rules
 
# Verify vendor detection with AST output
sentriflow --ast router.conf

Common causes:

Wrong vendor specified (Juniper config with Cisco vendor)
Config file encoding issues (try UTF-8)
Rules disabled in configuration

”Unknown Vendor”


# Explicitly specify the vendor
sentriflow -v cisco router.conf
 
# Check supported vendors
sentriflow --list-vendors

Supported vendors: cisco, cisco-nxos, juniper, paloalto, arista, fortinet, vyos, mikrotik, nokia-sros, huawei, extreme-exos, extreme-voss

Understanding Rule Selectors

Rules use selectors to match configuration sections. If a rule isn’t matching expected lines:

Selectors use case-insensitive prefix matching. The selector interface matches interface GigabitEthernet0/0, Interface Vlan100, etc.

Debug with AST output:


# View the parsed AST structure
sentriflow --ast router.conf
 
# Example output shows how config is parsed
# {
#   "vendor": { "id": "cisco", "name": "Cisco IOS" },
#   "ast": [
#     {
#       "type": "section",
#       "raw": "interface GigabitEthernet0/0",
#       "keyword": "interface",
#       "params": ["GigabitEthernet0/0"],
#       "children": [...]
#     }
#   ]
# }

Selector examples:


interface          → Matches all interfaces
interface Gi       → Matches GigabitEthernet interfaces
router bgp         → Matches BGP configuration
ip access-list     → Matches IP ACLs

Output Format Issues

SARIF Not Recognized

If your CI tool doesn’t recognize SARIF output:


# Verify SARIF structure (output to file via redirection)
sentriflow -f sarif router.conf > results.sarif
cat results.sarif | jq '.runs[0].results | length'

SARIF 2.1.0 is required by most tools. SentriFlow outputs compliant SARIF by default.

JSON Parsing Errors

JSON is the default output format:


# Default: structured JSON
sentriflow router.conf | jq '.results'
 
# Explicitly request JSON
sentriflow -f json router.conf | jq '.results'

Performance Issues

Slow on Large Configs

For configuration files over 10MB:


# Process multiple files
sentriflow file1.conf file2.conf file3.conf
 
# Use directory scanning for many files
sentriflow -D ./configs/ -R --progress

Processing Many Files


# Scan directory with progress indicator
sentriflow -D ./configs/ -R --progress
 
# Scan with custom extensions
sentriflow -D ./configs/ -R --extensions cfg,conf,txt

VS Code Extension Issues

Extension Not Loading

Check the extension is installed:
- Open Extensions panel (Ctrl+Shift+X)
- Search for “SentriFlow”
- Verify it shows as installed and enabled
Check the output panel:
- View → Output
- Select “SentriFlow” from dropdown
- Look for error messages
Reload VS Code:
- Ctrl+Shift+P → “Developer: Reload Window”

No Diagnostics Appearing

Check file association:


// settings.json
{
  "files.associations": {
    "*.conf": "sentriflow-config",
    "*.cfg": "sentriflow-config"
  }
}

Check enabled vendors:


{
  "sentriflow.enabledVendors": [
    "cisco",
    "cisco-nxos",
    "juniper"
  ]
}

Quick Fixes Not Available

Quick fixes are only available for rules that provide remediation:

Not all rules have automated fixes
Some fixes require manual review
Check if the rule’s remediation field is populated

Custom Rules Issues

Rule Not Evaluating

Verify your custom rule file:


# List rules to check if custom rule is loaded
sentriflow --json-rules ./my-rule.json --list-rules
 
# Run with custom rules
sentriflow --json-rules ./my-rule.json router.conf

Common JSON rule errors:


{
  "id": "MY-RULE-001",        // Must be unique
  "selector": "interface",     // Must match config sections
  "vendor": "cisco",           // Must be valid vendor
  // ...
}

TypeScript Rule Errors

For TypeScript rules that fail to load:


# Check TypeScript compilation
npx tsc --noEmit ./my-rule.ts
 
# Ensure correct exports
# Rule file must export default: export default myRule

Disabling Specific Rules

To skip rules that are causing issues:


# Disable specific rules by ID
sentriflow -d NET-AUTH-001,NET-IP-002 router.conf
 
# Or use comma-separated list
sentriflow --disable NET-LOG-001 router.conf

Getting More Help

Debug with AST


# View how your config is parsed
sentriflow --ast router.conf | jq '.ast'
 
# Check vendor detection
sentriflow --ast router.conf | jq '.vendor'

Reporting Issues

When reporting issues, include:

SentriFlow version: sentriflow --version
Node.js version: node --version
Operating system
Minimal config file that reproduces the issue
Full command you ran

Report issues at: github.com/sentriflow/sentriflow/issues

Next Steps

CLI Commands - Full command reference
Configuration - Config file options
Rule Authoring - Create custom rules