Security Insight - GitLab Orbit Security Analysis

AI agent that queries GitLab Orbit Knowledge Graph to surface security vulnerabilities automatically. Proven by dogfooding: found 18 bugs in itself, we fixed them, 39% improvement verified.

Comment

Inspiration

As developers, we run comprehensive security scans—SAST, secret detection, dependency scanning—on every commit. But when the pipeline turns green, a critical question remains unanswered: what vulnerabilities were actually found?

The results are scattered across CI/CD job logs, buried in JSON artifacts, hidden in security dashboards. To understand your security posture, you need to manually dig through multiple tools and interfaces. We wanted to fix this with AI.

GitLab Orbit Knowledge Graph contains all this security data in a unified graph. What if an AI agent could query it automatically
and surface actionable insights? That's how Security Insight was born.

## What it does

Security Insight is an AI-native security analysis tool with three implementations:

### 1. GitLab Duo Flow (Primary - Published to AI Catalog)

  • Automatically queries GitLab Orbit Knowledge Graph for security vulnerabilities
  • Analyzes findings from SAST, secret detection, dependency scanning, and more
  • Groups results by severity (Critical, High, Medium, Low)
  • Creates detailed security analysis reports as GitLab issues
  • Integrated into GitLab Duo AI workflows

### 2. Agent Skill (Cross-platform)

  • Compatible with Claude Code, GitLab Duo, and any Agent Skills-compatible AI
  • Installed at ~/.agents/skills/security-insight/
  • Enables natural language security queries: "Find critical vulnerabilities in this project"
  • Follows the Agent Skills specification for portability

### 3. Python CLI (Standalone)

  • Direct command-line interface: python src/security_scanner.py scan project-name
  • Queries remote GitLab Orbit API or local Orbit database
  • Perfect for automation and scripting

One tool, three ways to use it—flexibility for every workflow.

## How we built it

Tech Stack:

  • GitLab Orbit Knowledge Graph: Unified SDLC data including vulnerabilities, code definitions, security scans
  • Python 3.9+: Core implementation with requests for API calls
  • GitLab Duo Flow (v1 spec): YAML-based multi-agent workflow configuration
  • Agent Skills Specification: Cross-platform AI agent integration
  • GitLab CI/CD: Automated security scanning with SAST, Secret Detection, Dependency Scanning

Development Process:

  1. Orbit API Client (src/orbit_client.py):

    • Built secure wrapper around GitLab Orbit REST API
    • Implemented query methods: search(), traverse(), query()
    • Added _handle_response() for secure error handling (no token leakage)

  2. Security Scanner (src/security_scanner.py):

    • Created methods to query vulnerability entities in Orbit graph
    • Implemented severity-based grouping and analysis
    • Added project-wide security status aggregation

  3. GitLab Duo Flow (flow/security-insight-flow.yml):

    • Designed multi-component workflow using Flow Registry v1
    • Configured AgentComponent with security analysis prompts
    • Published to AI Catalog for community use

  4. Agent Skill (skills/security-insight/SKILL.md):

    • Wrote YAML frontmatter following Agent Skills specification
    • Documented slash commands and natural language patterns
    • Made it portable across AI platforms

  5. CI/CD Pipeline (.gitlab-ci.yml):

    • Integrated GitLab security scanning templates
    • Added Python syntax validation
    • Configured to run on every commit

## Challenges we ran into

### 1. GitLab Orbit Remote API Access (403 Errors) Initially, we couldn't access the remote Orbit API despite having a valid token. After troubleshooting, we discovered our namespace wasn't indexed yet. We pivoted to using the local Orbit CLI (glab orbit local) which worked perfectly for development
and testing.

### 2. GitLab Duo Flow YAML Syntax The Flow Registry v1 specification has strict requirements. Our first attempts failed because:

  • We placed include statements inside job definitions instead of top-level
  • We tried to create multi-agent flows with invalid input targeting
  • Solution: Simplified to single-agent flow with proper YAML structure

### 3. Git Authentication & Token Permissions Pushed into multiple authentication issues:

  • First token: Read-only, couldn't push
  • Second token: Guest role, insufficient permissions
  • Third token: Finally worked with Maintainer role
  • Learned: Token scope and project role both matter!

### 4. CI/CD Pipeline Not Creating Jobs Pipeline showed "no jobs" despite valid YAML because of overly restrictive rules. Removed the rules to allow jobs to run on all
commits.

### 5. Agent Skill Detection in Claude Code Despite correct installation at ~/.agents/skills/security-insight/, Claude Code didn't detect the skill. This appears to be a
platform limitation. The skill is correctly formatted and ready for when detection improves.

## Accomplishments that we're proud of

### 🔥 We Dogfooded Our Own Security Tool

This is our proudest achievement. We ran Security Insight on its own codebase:

Round 1 - Found Our Own Bugs:

  • 18 security issues discovered
  • 3 Critical: Token leakage in error messages, missing error sanitization, unsafe constructor parameters
  • 5 High: Input validation, dependencies, logging issues
  • 6 Medium: No CI/CD security scans, documentation gaps
  • 4 Low: Code quality improvements

The Fixes:

  • Added _handle_response() method to sanitize all error messages
  • Enforced environment-variable-only token sourcing
  • Integrated GitLab security scanning templates (SAST, Secret Detection, Dependency Scanning)
  • Fixed input validation and improved error handling

Round 2 - Verified the Fixes:

  • 11 security issues (down from 18)
  • 1 Critical (down from 3)
  • 3 High (down from 5)
  • 39% improvement!

This proves Security Insight works. We found real bugs in our security tool, fixed them, and verified the improvements—all
using the tool itself.

### 📦 Three Production-Ready Implementations

  • ✅ GitLab Duo Flow published to AI Catalog
  • ✅ Agent Skill tested and installed
  • ✅ Python CLI functional and documented

### 🏗️ Clean, Professional Codebase

  • Organized folder structure (src/, flow/, docs/, skills/)
  • Comprehensive documentation (README, installation guides, demo scripts)
  • MIT License for open source contribution
  • Full CI/CD pipeline with security scanning

### 🎯 Published to AI Catalog Our Flow is live and available for the GitLab community to use immediately.

## What we learned

### GitLab Orbit Knowledge Graph is Powerful Orbit unifies code definitions, dependencies, vulnerabilities, and security scans into a single queryable graph. This eliminates
the need to aggregate data from multiple sources manually. The SQL-like query interface makes it accessible to developers.

### Agent Skills Specification Enables Portability By following the Agent Skills spec with YAML frontmatter, we created a skill that works across multiple AI platforms—not just GitLab Duo. This cross-platform compatibility is the future of AI agents.

### GitLab Duo Flow Registry v1 is Robust Once we understood the specification, the Flow system proved powerful for building multi-step AI workflows. The ability to publish
to AI Catalog and share with the community is game-changing.

### Dogfooding Builds Credibility Testing our security tool on itself wasn't just a demo tactic—it found real bugs and made the project better. The 39% improvement
is measurable proof that Security Insight delivers value.

### Security Should Be Automated and Visible Developers shouldn't have to hunt for security findings. Automated AI agents that surface issues proactively will become essential
as codebases grow more complex.

## What's next for Security Insight - GitLab Orbit Security Analysis

### Short Term (Next 2 Weeks)

  • Improve Orbit Remote API Access: Work with GitLab to ensure namespace indexing and remote API reliability
  • Enhance Agent Skill Detection: Debug why Claude Code isn't detecting the skill and contribute fixes upstream
  • Add More Query Patterns: Expand security analysis to include code quality, licensing, and compliance checks

### Medium Term (Next 2 Months)

  • Build Additional Skills:

    • Dependency Impact Analysis: Query Orbit for dependency graphs and impact analysis
    • Pattern Finder: Detect anti-patterns and code smells using Orbit relationships
    • Risk Scorer: Calculate security risk scores based on vulnerability density and severity

  • Enterprise Features:

    • Multi-project security dashboards
    • Trend analysis over time
    • Integration with Jira/Linear for ticket creation
    • Slack/Teams notifications for critical findings

  • Community Contributions:

    • Create video tutorials
    • Write blog posts on Orbit Knowledge Graph usage
    • Contribute security query templates to GitLab docs

### Long Term (Next 6 Months)

  • AI-Powered Remediation Suggestions: Use LLMs to suggest code fixes for vulnerabilities
  • Automated Security PRs: Create merge requests that fix issues automatically
  • Custom Security Policies: Allow teams to define their own security thresholds and rules
  • GitLab Marketplace Integration: Package as official GitLab integration

The vision: Security Insight becomes the standard way developers interact with security data—turning passive scans into proactive, AI-driven security improvements.

Built With

  • agent-skills-specification
  • ai-agents
  • dependency-scanning-(gemnasium)
  • duckdb
  • gitlab-ci/cd
  • gitlab-duo-flow-(flow-registry-v1)
  • gitlab-orbit-knowledge-graph
  • gitlab-rest-api
  • python-3.9+
  • python-dateutil
  • requests
  • sast-(semgrep)
  • secret-detection
  • yaml
Share this project:

Updates