🧩 SentinAI Core

The open-source multi-agent security engine powering the SentinAI SaaS.

SentinAI Core is an autonomous AI security auditor designed to reason about intended access rules, simulate real-world exploits, and identify logical flaws (like IDOR and BFL) that traditional static analysis tools miss.

🧠 Architecture: The Orchestration Loop

SentinAI uses a specialised three-agent pipeline that works with any supported LLM provider:

1. The Architect: Maps the attack surface of a code diff, identifying routes, middleware, and potential data access points.
2. The Adversary: Acts as a red-team researcher, cross-referencing findings with a RAG-based vulnerability memory to hypothesise specific exploit vectors.
3. The Guardian: Evaluates findings against framework-level protections to suppress false positives and assign severity (LOW to CRITICAL).

🚀 Key Features

• Multi-Agent Reasoning: Context-aware security analysis that goes beyond pattern matching.
• Lethal Patterns: Specialised in Business Logic Flaws (BFL), OWASP Top 10, and 45 high-fidelity Smart Contract vulnerability signatures (Solana/Rust, EVM/Solidity, Aptos+Sui/Move).
• Traction: 236 organic npm downloads within 2 weeks of publishing — zero marketing.
• Provider-Agnostic: Swap AI backends with a single environment variable — no code changes required.
• Zero-Leakage Mode: Run entirely inside your own VPC with a self-hosted Ollama instance. Your source code never leaves your infrastructure.
• Elite Tiered Routing: Lightweight models handle fast diff mapping; heavy models handle exploit reasoning and final validation.

📦 Installation

npm install sentinai-core

🛠️ Usage

import { runOrchestrator } from 'sentinai-core';

const diff = '... your github diff string ...';

// Custom logger to capture agent states
const logger = (msg: string) => console.log(msg);

const findings = await runOrchestrator(diff, logger);

console.log(`Detected ${findings.length} vulnerabilities.`);

---

🌐 Provider Configuration

Set SENTINAI_PROVIDER to select your AI backend. All other env vars for that provider become active.

Gemini — Google AI Studio (default)

SENTINAI_PROVIDER=gemini
GEMINI_API_KEY=your_key_here

Best for: local development, prototyping.

---

Vertex AI — Google Cloud (enterprise)

SENTINAI_PROVIDER=vertex
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GOOGLE_CLOUD_LOCATION=europe-west1   # optional, defaults shown

Privacy guarantee: Vertex AI does not use your data for model training, and analysis never leaves your GCP project boundary.

Variable	Description
GOOGLE_CLOUD_PROJECT	Your GCP Project ID
GOOGLE_CLOUD_LOCATION	Vertex AI region (default: europe-west1)
GOOGLE_APPLICATION_CREDENTIALS	Path to service account JSON (not needed on Cloud Run)

---

Ollama — Self-Hosted / Zero-Leakage VPC

SENTINAI_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434   # optional, defaults shown
OLLAMA_MODEL_LITE=qwen2.5-coder:7b      # Architect agent
OLLAMA_MODEL_PRO=qwen2.5-coder:14b     # Adversary agent
OLLAMA_MODEL_ELITE=deepseek-r1:32b     # Guardian agent

Ollama uses its OpenAI-compatible /v1 endpoint under the hood, so no additional SDK is required.

Enterprise VPC deployment: Point OLLAMA_BASE_URL at your internal Ollama host. Your PR diffs are analysed entirely within your private network — zero external API calls.

Recommended models:

Tier	Default Model	Notes
Lite (Architect)	qwen2.5-coder:7b	Fast surface mapping
Pro (Adversary)	qwen2.5-coder:14b	Exploit reasoning
Elite (Guardian)	deepseek-r1:32b	Final validation

---

OpenAI

SENTINAI_PROVIDER=openai
OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=                        # optional — override for Azure or compatible endpoints
OPENAI_MODEL_LITE=gpt-4o-mini           # optional, defaults shown
OPENAI_MODEL_PRO=gpt-4o
OPENAI_MODEL_ELITE=o3

---

Anthropic

SENTINAI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_key_here
ANTHROPIC_MODEL_LITE=claude-haiku-4-5   # optional, defaults shown
ANTHROPIC_MODEL_PRO=claude-sonnet-4-5
ANTHROPIC_MODEL_ELITE=claude-opus-4-5

---

📊 Environment Variable Reference

Variable	Default	Description
SENTINAI_PROVIDER	gemini	Active AI provider: gemini | vertex | ollama | openai | anthropic
MIN_CONFIDENCE	40	Findings below this confidence % are suppressed
GEMINI_API_KEY	—	Required for gemini provider
GOOGLE_CLOUD_PROJECT	—	Required for vertex provider
GOOGLE_CLOUD_LOCATION	europe-west1	Vertex AI region
OLLAMA_BASE_URL	http://localhost:11434	Ollama host URL
OLLAMA_MODEL_LITE	qwen2.5-coder:7b	Ollama model for Architect tier
OLLAMA_MODEL_PRO	qwen2.5-coder:14b	Ollama model for Adversary tier
OLLAMA_MODEL_ELITE	deepseek-r1:32b	Ollama model for Guardian tier
OPENAI_API_KEY	—	Required for openai provider
OPENAI_BASE_URL	—	Optional Azure / compatible endpoint override
OPENAI_MODEL_LITE	gpt-4o-mini	OpenAI model for Architect tier
OPENAI_MODEL_PRO	gpt-4o	OpenAI model for Adversary tier
OPENAI_MODEL_ELITE	o3	OpenAI model for Guardian tier
ANTHROPIC_API_KEY	—	Required for anthropic provider
ANTHROPIC_MODEL_LITE	claude-haiku-4-5	Anthropic model for Architect tier
ANTHROPIC_MODEL_PRO	claude-sonnet-4-5	Anthropic model for Adversary tier
ANTHROPIC_MODEL_ELITE	claude-opus-4-5	Anthropic model for Guardian tier

---

🛡️ Responsible AI

• Confidence Scoring: Every finding includes a 0–100 confidence score; low-confidence findings are suppressed.
• JSON Fallback: Resilient three-strategy parsing prevents pipeline crashes during LLM hallucinations.
• Context Awareness: Understands middleware boundaries to reduce false positives.
• Prompt Injection Guards: All PR diffs are wrapped in <source_diff_for_analysis> tags and treated as untrusted data.
• Exponential Backoff Retry: All AI calls automatically retry up to 3 times (1s → 2s → 4s delay) on transient API errors (rate limits, 503s), ensuring reliability without manual intervention.
• Graceful Pattern Fallback: If patterns.json is missing or malformed at startup (e.g. before a build), the pipeline continues without the pattern library rather than crashing the process.

⚖️ License

Apache 2.0. See LICENSE for details.

Powered by SentinAI · SentinAI-core