Tharos

# Tharos

Modern AI-Powered Git Hook Security Scanner

Tharos is a specialized git commit hook scanner that acts as an intelligent gatekeeper for your codebase. It combines lightning-fast AST analysis with deep AI semantic insights to catch security vulnerabilities and leaks before they are committed to your repository.

✨ Features

🛡️ Core: Intelligent Git Hooks

Tharos's primary interface is your git workflow. It provides automated security gating that prevents high-risk code from ever leaving your machine.

• Pre-commit Gating: Block commits containing secrets, SQLi, or high-risk vulnerabilities.

• Polyglot AST Support: Native semantic analysis for TypeScript, JavaScript, Go, and Python.

• Interactive Magic Fixes: Collaboratively review, fix, or explain findings in the CLI.

• Policy-as-Code: Load organizational security policies from YAML (SOC2, GDPR, OWASP).

• Self-Healing Hooks: Automatically manages and repairs git hook integrity.

🔒 AI-Powered Security Analysis

• AST-Based Detection: Fast, accurate pattern matching for common vulnerabilities (SQLi, XSS, Secrets).
• Scanner Mindset: Context-aware analysis that ignores test files and mock data.
• AI Semantic Analysis: Deep understanding of code context and intent using Gemini/Groq.
• Risk Scoring: Intelligent commit blocking based on cumulative finding severity and AI risk scores.
• Suggested Fixes: AI-generated code snippets to resolve issues instantly at commit time.

4. GitHub Actions

- uses: actions/checkout@v3
- name: Tharos Security Check
  run: |
    npm install -g tharos
    tharos check

🧠 AI Provider Flexibility

Automatic fallback chain:

1. Google Gemini (Recommended, generous free tier)
2. Groq (Fast & Free inference)
3. Managed AI (Zero-config cloud fallback)

📦 Installation

NPM (Recommended)

npm install -g @collabchron/tharos

From Source

git clone https://github.com/chinonsochikelue/tharos.git
cd tharos
npm install
npm run build
npm link

🚀 Quick Start

1. Initialize Your Project

cd your-project
tharos init

This creates:

• tharos.yaml - Configuration file
• .git/hooks/pre-commit - Automatic validation
• .git/hooks/pre-push - CI/CD enforcement

2. Configure Your Policy

Choose a pre-built policy or create your own:

# 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. Set Up AI Providers (Optional but Recommended)

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

# 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

# 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:

tharos setup

4. Run Analysis

# Check all staged files
tharos check

# Analyze specific file
tharos analyze src/api/auth.ts

# Interactive review (Fix/Explain/Skip findings)
tharos analyze . --interactive

🧪 Automated Testing

Tharos includes a built-in test suite to verify security policies and engine performance.

# 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

tharos.yaml Example

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

Installation

1. Open VSCode
2. Press Ctrl+Shift+X (Extensions)
3. Search for "Tharos"
4. Click Install

Features

• 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

Configuration

{
  "tharos.enableAI": true,
  "tharos.severity": "warning",
  "tharos.corePath": ""  // Auto-detected
}

📚 Policy Library

Tharos includes comprehensive pre-built policies:

🏗️ Architecture

┌─────────────────────────────────────────┐
│           Tharos Ecosystem              │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────┐  ┌──────────┐  ┌───────┐│
│  │   CLI    │  │  VSCode  │  │GitHub ││
│  │   Tool   │  │Extension │  │Action ││
│  └────┬─────┘  └────┬─────┘  └───┬───┘│
│       │             │             │    │
│       └─────────────┼─────────────┘    │
│                     │                  │
│            ┌────────▼────────┐         │
│            │  tharos-core    │         │
│            │  (Go Binary)    │         │
│            │  - AST Analysis │         │
│            │  - AI Integration│        │
│            └────────┬────────┘         │
│                     │                  │
│       ┌─────────────┼─────────────┐   │
│       │             │             │   │
│  ┌────▼────┐  ┌────▼────┐  ┌────▼───┐│
│  │ Ollama  │  │ Gemini  │  │  Groq  ││
│  │ (Local) │  │ (Cloud) │  │(Cloud) ││
│  └─────────┘  └─────────┘  └────────┘│
└─────────────────────────────────────────┘

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# 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

Startup / Small Team

# Quick setup with OWASP
tharos init
cp policies/owasp-top10.yaml tharos.yaml
export GROQ_API_KEY="your-key"

Enterprise / Compliance-Focused

# 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"

Open Source Project

# Code quality focus
tharos init
cp policies/code-quality.yaml tharos.yaml
# Use local Ollama (no API keys needed)
ollama serve

🔐 Security

Tharos takes security seriously:

• Local-First: AST analysis runs entirely locally
• Privacy: AI analysis is optional and configurable
• No Data Collection: We don't collect or store your code
• Open Source: Full transparency, audit the code yourself

📊 Performance

• AST Analysis: < 100ms for typical files
• AI Insights: < 2s with Groq, < 5s with Gemini
• VSCode Extension: No UI blocking, async analysis
• Git Hooks: < 1s for pre-commit checks

🗺️ Roadmap

• [ ] Additional language support (C++, C#, PHP, Ruby)
• [ ] Cloud dashboard for team management
• [ ] Custom rule builder UI
• [ ] IDE integrations (JetBrains, Sublime)
• [ ] CI/CD platform integrations (GitLab, CircleCI)
• [ ] Machine learning model training on your codebase

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

• OWASP for security guidelines
• Google Gemini team for AI capabilities
• Groq for fast inference
• The open-source community

💬 Support

• Documentation: https://tharos.vercel.app
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join our community

Built with ❤️ by developers, for developers

🦊 Tharos - Because security shouldn't slow you down