🛡️ GitAgent SecureBot

AI-powered security scanner & auto-fixer that finds vulnerabilities — and writes the patches itself.

Built for the Lzyr Builder Challenge using GitAgent.

🎬 Live Demo · 🚀 Quick Start · 🧠 Architecture · 🩹 Demo Flow · 📐 Design Decisions

---

⚡ TL;DR

You paste a GitHub repo URL (or click demo for zero-setup). SecureBot — a multi-agent system on the GitAgent SDK — scans for OWASP Top 10 vulnerabilities, hardcoded secrets, and known CVEs. Findings stream live to your browser. Click any finding and a second agent generates a minimal, secure patch with a side-by-side diff.

Repo URL ──▶ 🔍 Scanner Agent ──▶ Findings (live SSE) ──▶ 🩹 Click "Auto-Fix" ──▶ Fixer Agent ──▶ Diff

💡 Live mode uses Lyzr / OpenAI / Anthropic via the GitAgent SDK with custom tools, hooks, skills, and a multi-agent workflow. Demo mode ships scripted output so anyone can experience the full UX in 60 seconds with zero setup.

---

🎯 Why this submission stands out

The challenge rewards execution, creativity, product thinking, speed of shipping, and agent workflow design. SecureBot hits each:

Criterion	How SecureBot delivers
🛠 Execution	A working full-stack product, not a sketch. Real custom tools, real hooks, real CWE mappings, real fix templates. Builds clean, deploys in one click.
✨ Creativity	Two-agent pipeline (Scanner → Fixer) glued by a workflow YAML. Tool-anchored LLM pattern — regex rules find anchors, LLM does the reasoning. Fast, reliable, structured output.
🎯 Product thinking	DEMO_MODE=true → 60-second zero-key demo. OPENAI_API_KEY set → live agent mode. One-click deploy buttons for Vercel, Netlify, Codespaces.
⏱ Speed of shipping	Single Next.js codebase (no Python bridge), shipped in hours. CI passes on every commit. Production-ready Dockerfile + multi-cloud configs.
🧬 Agent workflow design	Uses every GitAgent primitive: SDK query(), tool(), programmatic hooks, declarative tools (YAML + shell), skills, workflows, memory, identity files (SOUL/RULES/DUTIES), compliance config, multi-model fallback.

---

🎬 Live Demo

Zero-config: click any deploy button above ⤴︎ — defaults to demo mode, no keys needed.

The flow you see in 60 seconds:

┌──────────────────────────────────────────────────────────────────────┐
│  🛡️ SecureBot                                  GitAgent ↗  Source ↗  │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│              Your codebase has bugs.                                 │
│              SecureBot finds them. And fixes them.                   │
│                                                                      │
│      [ github.com/org/repo  or  'demo'        ] [▶ Scan with…  ]    │
│                                                                      │
│       Try:  [Demo (vulnerable Node.js)]  [OWASP Juice Shop]  …      │
└──────────────────────────────────────────────────────────────────────┘

After clicking ▶ Scan:
┌─────────────────────────────────┬──────────────────────────────────┐
│ Agent stream (live)             │ Findings (7)                     │
│ ─────────────────────           │ ────────────────────             │
│ ● ● ●  gitagent · live          │  [CRITICAL] CWE-798              │
│                                 │  Hardcoded OpenAI Key  🩹 Auto-Fix│
│ [tool_call] find_secrets        │                                  │
│ [finding]  CRITICAL  CWE-798    │  [CRITICAL] CWE-89               │
│ [tool_call] scan_file           │  SQL Injection         🩹 Auto-Fix│
│ [finding]  CRITICAL  CWE-89     │                                  │
│ [finding]  CRITICAL  CWE-78     │  [HIGH]     CWE-79               │
│ [finding]  HIGH      CWE-338    │  DOM XSS               🩹 Auto-Fix│
│ [summary]  7 findings · 3.4s    │   ↓ click Auto-Fix              │
│                                 │  ┌─ before ─┐┌─ after ─┐         │
│ Generating summary…             │  │vulnerable││ secure  │         │
│                                 │  └──────────┘└─────────┘         │
└─────────────────────────────────┴──────────────────────────────────┘

---

🚀 Quick Start

Option A — One-click cloud deploy

Platform	Action
Vercel
Netlify
GitHub Codespaces

Option B — Local dev (3 commands)

git clone https://github.com/Youranalyst-coder/gitagent-securebot.git
cd gitagent-securebot
npm install --ignore-scripts && npm run dev

Open http://localhost:3000 → click "Scan with SecureBot".

The --ignore-scripts flag avoids an unrelated postinstall in @googleworkspace/cli (not used by SecureBot). The app itself works perfectly.

Option C — Docker

docker compose up --build
# → http://localhost:3000

Option D — Live Mode (Real GitAgent SDK)

cp .env.example .env.local
# Edit .env.local:
#   DEMO_MODE=false
#   OPENAI_API_KEY=sk-...        (or LYZR_API_KEY, or ANTHROPIC_API_KEY)
npm run dev

Now SecureBot uses the actual GitAgent SDK — runs custom tools, fires hooks, the works.

---

🧠 Architecture

flowchart TB
    User[👤 User<br/>browser] -->|repo URL| FE[🖥 Next.js Frontend<br/>app/scan/page.tsx]

    FE -->|POST /api/scan| API1[📡 Scan API Route<br/>SSE stream]
    API1 -->|SDK query| Scanner[🔍 Scanner Agent<br/>skills/scan-security]

    Scanner -->|custom tools| Tools1[🛠 scan_file<br/>find_secrets<br/>check_deps]
    Scanner -->|preToolUse hook| Audit[🪝 Audit Hook<br/>blocks rm -rf, etc.]
    Scanner -->|finding blocks| API1
    API1 -->|SSE events| FE

    FE -->|click 🩹 Fix → POST /api/fix| API2[📡 Fix API Route<br/>SSE stream]
    API2 -->|SDK query| Fixer[🩹 Fixer Agent<br/>skills/fix-vulnerability]
    Fixer -->|generate_fix tool| Tools2[💊 Canonical CWE<br/>fix templates]
    Fixer -->|fix block| API2
    API2 -->|SSE events| FE

    subgraph AgentRepo ["📁 agent/ — the agent IS a git repo"]
        SOUL[SOUL.md<br/>identity]
        RULES[RULES.md<br/>safety]
        DUTIES[DUTIES.md<br/>scope]
        AGENT[agent.yaml<br/>model + compliance]
        SKILL1[skills/scan-security]
        SKILL2[skills/fix-vulnerability]
        WORK[workflows/scan-and-fix.yaml]
        DECL[tools/grep-secrets.yaml]
        HOOKS[hooks/audit.sh]
        MEM[memory/MEMORY.md]
    end

    Scanner -.identity.- SOUL
    Scanner -.skill.- SKILL1
    Fixer -.skill.- SKILL2

    style User fill:#0d1117,stroke:#58a6ff,color:#fff
    style FE fill:#21262d,stroke:#58a6ff,color:#fff
    style Scanner fill:#1f6feb,stroke:#58a6ff,color:#fff
    style Fixer fill:#3fb950,stroke:#3fb950,color:#fff
    style Tools1 fill:#21262d,stroke:#bc8cff,color:#fff
    style Tools2 fill:#21262d,stroke:#bc8cff,color:#fff
    style Audit fill:#21262d,stroke:#f85149,color:#fff

Loading

---

🧩 GitAgent primitives — coverage matrix

GitAgent Primitive	Where in this project	What it does
SDK query()	lib/gitagent-client.ts	Streams agent events to SSE
SDK tool()	lib/tools/*.ts (4 tools)	Custom security scanners
Programmatic hooks	lib/hooks.ts	preToolUse blocks rm -rf, audits everything
Declarative tool	agent/tools/grep-secrets.yaml + .sh	Shell-script tool from YAML
Script hook	agent/hooks/audit.sh	Filesystem audit log
Skills	agent/skills/{scan-security,fix-vulnerability}/SKILL.md	Composable instruction modules
Workflow	agent/workflows/scan-and-fix.yaml	Chains Scanner → Fixer
Identity files	agent/{SOUL,RULES,DUTIES}.md	Personality, constraints, scope
Memory	agent/memory/MEMORY.md	Git-committed, append-only
Compliance	agent.yaml → compliance: block	risk_level: high, audit logging
Multi-model fallback	agent.yaml → model.fallback	Lyzr → OpenAI → Anthropic
Cost tracking	UI status bar	Surfaced from query.costs()

---

🔍 Vulnerabilities detected

Each finding maps to a real CWE identifier with a canonical fix template:

CWE	Vulnerability	Canonical Fix
CWE-89	SQL Injection	Parameterized queries
CWE-78	Command Injection	spawn with arg array
CWE-94	Code Injection (eval)	JSON.parse
CWE-79	DOM XSS (innerHTML)	textContent / DOMPurify
CWE-327	Weak hashing (MD5/SHA1)	SHA-256 / bcrypt
CWE-338	Math.random() for secrets	crypto.randomBytes
CWE-502	Unsafe deserialization	safe_load / JSON
CWE-798	Hardcoded secrets	process.env + rotate
CWE-352	CSRF disabled	Re-enable middleware
CWE-1104	Vulnerable dependencies	Bump to patched version

---

📂 Project Structure

gitagent-securebot/
├── 📁 agent/                       # The GitAgent agent IS a git repo
│   ├── agent.yaml                  # Model, tools, runtime, compliance
│   ├── SOUL.md                     # Identity & output discipline
│   ├── RULES.md                    # 8 hard safety rules
│   ├── DUTIES.md                   # Scope: scan vs fix duties
│   ├── skills/scan-security/       # OWASP Top 10 scanning skill
│   ├── skills/fix-vulnerability/   # CWE-mapped fix skill
│   ├── workflows/scan-and-fix.yaml # Multi-agent workflow
│   ├── tools/grep-secrets.{yaml,sh}
│   ├── hooks/{hooks.yaml,audit.sh,alert.sh,session-start.sh}
│   └── memory/MEMORY.md
├── 📁 app/                         # Next.js 14 App Router
│   ├── api/scan/route.ts           # POST /api/scan — SSE
│   ├── api/fix/route.ts            # POST /api/fix — SSE
│   ├── scan/page.tsx               # Real-time dashboard
│   ├── components/                 # 5 React components
│   ├── page.tsx                    # Landing page
│   └── layout.tsx
├── 📁 lib/
│   ├── gitagent-client.ts          # SDK wrapper, demo mode, SSE bridge
│   ├── hooks.ts                    # Programmatic preToolUse + onError
│   ├── tools/                      # 4 custom GitAgent SDK tools
│   └── types.ts
├── 🐳 Dockerfile, docker-compose.yml
├── ☁  vercel.json, netlify.toml
├── 🤖 .github/workflows/ci.yml
├── 📐 ARCHITECTURE.md              # Design decisions for submission
├── 📜 README.md
└── 📋 LICENSE

---

🎬 Demo Flow

1. Open http://localhost:3000 → click "▶ Scan with SecureBot" (default value demo)
2. Land on /scan?demo=1
3. Watch the left panel light up with [tool_call] find_secrets → [finding] CRITICAL CWE-798 …
4. Right panel populates with vulnerability cards as findings stream
5. Summary bar crystallizes: 7 findings · 4 critical / 2 high / 1 medium
6. Click 🩹 Auto-Fix on any card → second agent runs → diff appears inline

🎥 Demo Video — 3 minutes (coming soon — record against running app)

---

🏆 Submission Checklist

• ✅ GitHub repository — Youranalyst-coder/gitagent-securebot
• ✅ Live deployment — see deploy buttons above
• ✅ Architecture document — ARCHITECTURE.md
• ✅ Working demo (zero config via DEMO_MODE=true)
• ✅ Live mode using real GitAgent SDK with custom tools + hooks
• ✅ Multi-agent workflow (Scanner → Fixer chained via workflow YAML)
• ✅ Uses every major GitAgent primitive (12/12 — see matrix above)
• ✅ Production-ready: Dockerfile, CI, multiple deploy targets
• 📹 3–5 min demo video

---

📜 License

MIT — see LICENSE.

🙏 Credits

• GitAgent — universal git-native agent framework
• Lyzr AI Studio — primary model provider, free tier
• OWASP & MITRE CWE — vulnerability taxonomy

---

Built with ❤️ for the Lzyr Builder Challenge

⭐ Star this repo if it helped you understand the GitAgent SDK ⭐