-
-
tangerine tui
-
tangerine structure
-
workflow
-
model tier
Tangerine
AI-Powered Security Analysis for the Modern Development Era
Inspiration
The software development landscape has fundamentally shifted. With the rise of AI-assisted coding tools like GitHub Copilot, Cursor, and ChatGPT, developers are generating code faster than ever before. While this accelerates development velocity, it introduces critical security blind spots that traditional tools cannot address.
The core issue: Production systems are being deployed with critical vulnerabilities that could have been caught with proper analysis.
| Challenge | Impact |
|---|---|
| AI-generated code inherits vulnerabilities from training data | Insecure patterns propagate at scale |
| Rapid prototyping prioritizes functionality over security | Security reviews deferred indefinitely |
| Dependency sprawl across hundreds of packages | CVE tracking becomes impossible manually |
| Traditional SAST tools produce overwhelming false positives | Alert fatigue leads to ignored warnings |
| Security expertise is scarce | Most teams lack dedicated security engineers |
What it does
Tangerine is an AI-powered security analyst that brings expert-level vulnerability detection directly into your terminal. Through natural conversation, developers can analyze entire codebases for security issues, understand complex vulnerability chains, and receive actionable remediation guidance.
Multi-Agent Security System
Tangerine employs a hierarchical multi-agent architecture where specialized agents handle specific security domains:
| Agent | Security Focus | Output |
|---|---|---|
| Security Orchestrator | Codebase exploration, data flow tracing, remediation guidance, agent delegation | Conversation |
recon_agent |
Secrets, API keys, debug endpoints, information disclosure | .security/recon-findings.md |
access_agent |
Authentication bypass, IDOR, privilege escalation, CORS, JWT vulnerabilities | .security/access-findings.md |
inject_agent |
SQL injection, XSS, command injection, SSRF, path traversal | .security/inject-findings.md |
data_agent |
Weak cryptography, race conditions, insecure deserialization, privacy leaks | .security/data-findings.md |
supply_chain_agent |
CVE detection, outdated dependencies, infrastructure misconfigurations (Google Search) | .security/supply-chain-findings.md |
pentest_agent |
Exploit verification, payload testing, Docker sandboxing | .security/pentest-findings.md |
Tool Suite
The agent has access to 15 specialized tools for comprehensive codebase analysis and verification:
| Category | Tools | Purpose |
|---|---|---|
| File System | ls, glob, grep, read_file, read_many_files, write_file, edit_file, mkdir |
Navigate and analyze codebase structure |
| Execution | run_command, command_status, kill_command |
Run security testing commands |
| Sandboxing | start_sandbox, sandbox_exec, upload_to_sandbox, stop_sandbox |
Docker-based exploit verification |
| Research | google_search |
Real-time CVE and security advisory lookup |
Execution Modes
| Mode | Indicator | Behavior | Recommended For |
|---|---|---|---|
| YOLO | [YOLO] |
Automatic tool execution | Trusted environments, CI/CD |
| Safe | [SAFE] |
User confirmation required | Untrusted code, learning |
How we built it
Core Technologies
| Component | Technology | Purpose |
|---|---|---|
| Runtime | Node.js 20+ | TypeScript execution environment |
| AI Framework | Google Agent Development Kit (ADK) | Multi-agent orchestration and tool management |
| Language Model | Gemini 3 Flash/Pro | Large context analysis with reasoning |
| UI Framework | Ink (React for CLI) | Interactive terminal interface |
| Search | Google Search | Real-time CVE research |
| Verification | Docker | Sandboxed environment for exploit testing |
| Validation | Zod | Type-safe tool parameter schemas |
Why Gemini 3
We selected Gemini 3 as the foundation because of capabilities critical to security analysis:
| Capability | Benefit for Security Analysis |
|---|---|
| 1M+ Token Context | Analyze entire codebases without chunking or summarization loss |
| Native Tool Calling | Reliable structured output for file operations and command execution |
| Thinking Modes | Adjustable reasoning depth for complex vulnerability chains |
| Thought Signatures | Maintained context across multi-turn tool interactions |
| Fast Inference | Real-time streaming for responsive terminal experience |
The extended context window is critical for security analysis, where understanding the full data flow from user input to database query, potentially spanning dozens of files, is essential for accurate vulnerability detection.
Challenges we ran into
ADK Compatibility with Gemini 3
The most significant challenge was achieving stable tool calling with Gemini 3 models.
Problem: Gemini 3 sends an explicit
STOPfinish reason after tool calls, which caused the ADK agent loop to terminate prematurely before processing the tool response.
Our Solution:
We contributed a fix upstream to the official ADK repository:
- Track function responses within each loop iteration
- Continue the loop when a tool response needs to be sent back to the model
- Add proper Gemini 3 model detection for code executor compatibility
| File Modified | Change |
|---|---|
llm_agent.ts |
Added hasFunctionResponse tracking in runAsyncImpl loop |
model_name.ts |
Added isGemini3Model and isGemini2OrLaterModel helpers |
built_in_code_executor.ts |
Updated to use new model detection |
Thinking Mode Requirements
We discovered that Gemini 3 requires "thinking" to be enabled for multi-turn tool calling conversations. Without thinking enabled, the API rejects requests with errors about missing thought signatures.
Agent Coordination
Designing the specialist agent system required careful consideration of control flow. Each specialist is configured with:
disallowTransferToParent: true
disallowTransferToPeers: true
This ensures agents complete their scans fully before returning control to the orchestrator.
Accomplishments that we are proud of
| Accomplishment | Description |
|---|---|
| Open Source Contribution | ADK fixes for Gemini 3 compatibility submitted upstream, helping other developers |
| Natural Language Security | Users ask questions like "Are there SQL injection vulnerabilities in auth?" and receive contextual responses |
| OWASP Coverage | Multi-agent system covers OWASP Top 10 with specialized expertise |
| Developer Experience | Terminal-native interface with streaming, syntax highlighting, and Safe Mode |
| Actual Verification | Pentest agent proves vulnerabilities are real by exploiting them in a sandbox |
| Actionable Output | Findings written to markdown with severity ratings, code locations, and remediation steps |
What we learned
| Learning | Insight |
|---|---|
| Large Context Models | The ability to analyze an entire codebase in a single context window fundamentally changes vulnerability detection |
| Verified Exploits | Static analysis is not enough; using agents to verify exploits in a sandbox builds much higher trust |
| Thinking Modes | Gemini 3's reasoning levels significantly impact result quality for complex analysis |
| Tool Design | Clear, consistent tool interfaces reduce hallucination and improve reliability |
What is next for Tangerine
| Initiative | Description | Status |
|---|---|---|
| IDE Integration | VS Code extension for inline vulnerability highlighting | Planned |
| CI/CD Pipeline | GitHub Action for automated scanning on pull requests | Planned |
| Auto-Remediation | Agent-assisted code fixes with diff preview | In Design |
| Custom Rules | User-defined security policies for organization requirements | Planned |
| Report Generation | Comprehensive assessment reports in multiple formats | Planned |
| Historical Tracking | Vulnerability trends across commits and releases | Future |
Try It
Repository: https://github.com/victorbash400/Tangerine
