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 or VS Code.
Policy-as-Code: Load organizational security policies from YAML (SOC2, GDPR, OWASP).

🧩 VS Code Extension (v1.0.2)

Zero-Config: Bundled binaries for Windows, macOS, and Linux. No installation required.
Magic Fixes: Lightbulb icons propose AI-powered security patches directly in your editor.
Precise Highlighting: Native squiggly lines point to the exact token causing the risk.
Scan-on-Open: Instant feedback the moment you open a file.

🔒 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.

4. GitHub Actions (Official Action)

Integrate Tharos directly into your GitHub Security dashboard:

- 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.

🧠 AI Provider Flexibility

Automatic fallback chain:

Google Gemini (Recommended, generous free tier)
Groq (Fast & Free inference)
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

Open VSCode
Press Ctrl+Shift+X (Extensions)
Search for "Tharos"
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:

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.

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

🎯 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

🔐 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
Sponsor: GitHub Sponsors

Built with ❤️ by developers, for developers

🦊 Tharos - Because security shouldn't slow you down

Name		Name	Last commit message	Last commit date
.github		.github
.tharos-backup/20260208_223549		.tharos-backup/20260208_223549
audit_samples		audit_samples
dashboard		dashboard
dist		dist
docs		docs
go-core		go-core
policies		policies
release_bundle		release_bundle
releases		releases
scripts		scripts
src		src
tharos-action		tharos-action
tharos-vscode		tharos-vscode
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES_v1.2.0.md		RELEASE_NOTES_v1.2.0.md
RELEASE_NOTES_v1.3.0.md		RELEASE_NOTES_v1.3.0.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
bad_code_results.json		bad_code_results.json
build_log.txt		build_log.txt
check_output.txt		check_output.txt
debug_go.txt		debug_go.txt
fennec-0.1.0.tgz		fennec-0.1.0.tgz
final_check.txt		final_check.txt
final_check_v3.txt		final_check_v3.txt
groq_debug_go.txt		groq_debug_go.txt
groq_test.txt		groq_test.txt
help.txt		help.txt
lefthook.yml		lefthook.yml
multi_vuln_results.json		multi_vuln_results.json
package-lock.json		package-lock.json
package.json		package.json
results_test.sarif		results_test.sarif
semantic_check.txt		semantic_check.txt
test-cors.js		test-cors.js
test-fix.js		test-fix.js
test.sh		test.sh
test_output.txt		test_output.txt
tharos.yaml		tharos.yaml
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation