Tharos: Intelligent, Unbreakable Code Policy Enforcement
npm install @collabchron/tharos
yaml
- uses: actions/checkout@v4
- name: Tharos Security Scan
uses: ./tharos-action # In your repo use collabchron/tharos/tharos-action@v1
with:
path: '.'
ai: true
sarif: 'results.sarif'
`
This automatically uploads findings to the Security tab of your repository.
$3
Automatic fallback chain:
1. Google Gemini (Recommended, generous free tier)
2. Groq (Fast & Free inference)
3. Managed AI (Zero-config cloud fallback)
π¦ Installation
$3
`bash
npm install -g @collabchron/tharos
`
$3
`bash
git clone https://github.com/chinonsochikelue/tharos.git
cd tharos
npm install
npm run build
npm link
`
π Quick Start
$3
`bash
cd your-project
tharos init
`
This creates:
- tharos.yaml - Configuration file
- .git/hooks/pre-commit - Automatic validation
- .git/hooks/pre-push - CI/CD enforcement
$3
Choose a pre-built policy or create your own:
`bash
Use OWASP Top 10
cp node_modules/tharos/policies/owasp-top10.yaml tharos.yaml
Use SOC 2
cp node_modules/tharos/policies/soc2.yaml tharos.yaml
Use GDPR
cp node_modules/tharos/policies/gdpr.yaml tharos.yaml
`
$3
Tharos works without AI but provides deeper insights with it enabled. Choose either provider (both have free tiers):
#### π§ Option 1: Google Gemini (Recommended)
Best for: Powerful analysis, generous free tier
`bash
Get your API key from https://makersuite.google.com/app/apikey
export GEMINI_API_KEY="your-gemini-key-here"
Or on Windows PowerShell:
$env:GEMINI_API_KEY="your-gemini-key-here"
`
#### β‘ Option 2: Groq (Fast & Free)
Best for: Speed, low latency
`bash
Get your free API key from https://console.groq.com
export GROQ_API_KEY="your-groq-key-here"
Or on Windows PowerShell:
$env:GROQ_API_KEY="your-groq-key-here"
`
Check your setup:
`bash
tharos setup
`
$3
`bash
Check all staged files
tharos check
Analyze specific file
tharos analyze src/api/auth.ts
Interactive review (Fix/Explain/Skip findings)
tharos analyze . --interactive
`
---
$3
Tharos includes a built-in test suite to verify security policies and engine performance.
`bash
Run the automated security test suite
node scripts/run-tests.cjs
`
This suite tests Tharos against the audit_samples/ directory, ensuring no regressions in vulnerability detection.
π Configuration
$3
`yaml
name: "My Project Security Policy"
version: "1.0.0"
Built-in AST analysis is ALWAYS enabled for TS, JS, Go, and Python.
You can add custom regex patterns under the security section.
security:
enabled: true
rules:
- pattern: "DANGEROUS_INTERNAL_API"
message: "Internal API bypass detected"
severity: "critical"
AI configuration
ai:
enabled: true
provider: "auto" # auto, ollama, gemini, groq
min_risk_score: 60 # Filter noise; only show high-confidence AI insights
`
π§ VSCode Extension
$3
1. Open VSCode
2. Press Ctrl+Shift+X (Extensions)
3. Search for "Tharos"
4. Click Install
$3
- Real-time Analysis: See issues as you save
- Hover Insights: Rich tooltips with AI recommendations
- Quick Fixes: Apply suggested changes with one click
- Status Bar: Live issue counter
$3
`json
{
"tharos.enableAI": true,
"tharos.severity": "warning",
"tharos.corePath": "" // Auto-detected
}
`
π Policy Library
Tharos includes comprehensive pre-built policies:
| Policy | Description | Rules | Use Case |
|--------|-------------|-------|----------|
| owasp-top10.yaml | OWASP Top 10 2021 | 50+ | General web security |
| soc2.yaml | SOC 2 Type II | 40+ | SaaS compliance |
| gdpr.yaml | GDPR Compliance | 35+ | EU data protection |
| pci-dss.yaml | PCI-DSS v4.0 | 45+ | Payment processing |
| code-quality.yaml | Best Practices | 60+ | Code maintainability |
ποΈ Architecture
`
βββββββββββββββββββββββββββββββββββββββββββ
β Tharos Ecosystem β
βββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββ ββββββββββββ βββββββββ β
β β CLI β β VSCode β βGitHub β β
β β Tool β βExtension β βAction β β
β ββββββ¬ββββββ ββββββ¬ββββββ βββββ¬ββββ β
β β β β β
β βββββββββββββββΌββββββββββββββ β
β β β
β ββββββββββΌβββββββββ β
β β tharos-core β β
β β (Go Binary) β β
β β - AST Analysis β β
β β - AI Integrationβ β
β ββββββββββ¬βββββββββ β
β β β
β β β
β βββββββββββββββββββββββββββββ β
β β β β
β ββββββΌβββββ ββββββΌββββ β
β β Gemini β β Groq β β
β β (Cloud) β β(Cloud) β β
β βββββββββββ ββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββ
`
π€ Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
$3
`bash
Clone repository
git clone https://github.com/chinonsochikelue/tharos.git
cd tharos
Install dependencies
npm install
Build Go core
cd go-core
go build -o tharos-core.exe main.go
Build CLI
cd ..
npm run build
Run tests
npm test
`
π Documentation
Full documentation available at https://tharos.vercel.app
- Getting Started Guide
- Policy Configuration
- AI Integration
- VSCode Extension
- API Reference
π― Use Cases
$3
`bash
Quick setup with OWASP
tharos init
cp policies/owasp-top10.yaml tharos.yaml
export GROQ_API_KEY="your-key"
`
$3
`bash
SOC 2 + GDPR + PCI-DSS
tharos init
Combine multiple policies in tharos.yaml
Set up managed AI endpoint
export THAROS_MANAGED_KEY="your-enterprise-key"
`
$3
`bash
Code quality focus
tharos init
cp policies/code-quality.yaml tharos.yaml
``