sanctionctl

CLI tool for OFAC/sanctions screening - check individuals and businesses against global sanctions lists.

Installation

npm install -g sanctionctl
# or
npx sanctionctl <command>

Commands

Screen a Name

# Basic screening
sanctionctl check "Nicolas Maduro"

# Filter by entity type
sanctionctl check "Bank Rossiya" --type business

# Adjust match threshold
sanctionctl check "Putin" --min-match 0.80

# JSON output (for automation)
sanctionctl check "Kim Jong Un" --json

Batch Screening

Screen multiple names from a file:

# One name per line
sanctionctl batch customers.txt

# JSON array input
sanctionctl batch customers.json

# CSV output
sanctionctl batch customers.txt --csv --output results.csv

# JSON output
sanctionctl batch customers.txt --json --output results.json

Get Explanation (for AI agents)

sanctionctl explain "Vladimir Putin"

Returns structured JSON with risk assessment, recommended actions, and match details.

View Database

# Database statistics
sanctionctl stats

# List all sanctioned entities
sanctionctl list

# Filter by type
sanctionctl list --type person

# Filter by source
sanctionctl list --source us_ofac

Other Commands

# List available sanctions sources
sanctionctl sources

# Show risk thresholds
sanctionctl thresholds

Risk Levels

| Level | Score | Meaning | |-------|-------|---------| | 🚨 CRITICAL | ≥95% | Near-exact match. Block transaction. | | ⛔ HIGH | ≥85% | Very likely match. Manual review required. | | ⚠️ MEDIUM | ≥70% | Possible match. Additional verification needed. | | ⚡ LOW | ≥50% | Weak match. Likely false positive. | | ✅ CLEAR | <50% | No significant match. |

Supported Sources

| Code | Source | |------|--------| | us_ofac | US Treasury OFAC SDN List | | us_csl | US Consolidated Screening List | | us_bis_entity | US BIS Entity List | | un_consolidated | UN Consolidated Sanctions | | eu_consolidated | EU Financial Sanctions | | uk_ofsi | UK OFSI Consolidated List |

Programmatic Usage

import { screenName, screenBatch } from 'sanctionctl';

// Screen a single name
const result = screenName({
  name: 'Nicolas Maduro',
  type: 'person',
  minMatch: 0.70,
});

console.log(result.hasMatches);  // true
console.log(result.riskLevel);   // 'critical'
console.log(result.matches[0].name);  // 'MADURO MOROS, Nicolas'

// Batch screening
const batchResult = screenBatch([
  { name: 'John Smith' },
  { name: 'El Chapo' },
  { name: 'Jane Doe' },
]);

console.log(batchResult.matchCount);  // 1

Exit Codes

• 0 - No matches (clear)
• 1 - Matches found (or high/critical risk)

This allows integration with CI/CD pipelines:

sanctionctl check "Customer Name" || echo "Sanctions match found!"

Integration with AI Agents

The explain command returns agent-friendly JSON:

sanctionctl explain "Hezbollah" | jq .riskAssessment

{
  "level": "critical",
  "score": 1.0,
  "hasMatches": true,
  "interpretation": "Near-exact match to sanctioned entity...",
  "action": "BLOCK transaction and escalate to compliance officer..."
}

Related Tools

• achctl - ACH file processing
• finctl-cli - Income analysis
• creditctl - Credit scoring
• mortctl - Mortgage qualification

Disclaimer

This tool includes a sample sanctions database for demonstration purposes. For production use, integrate with official OFAC, UN, and other sanctions data sources. Consider using moov-io/watchman for production sanctions screening.

Author

Satyan Avatara - Avatara Consulting

License

Apache-2.0