InfraGuard AI - Orbit-Powered IaC Governance

AI-powered infrastructure promotion governance using GitLab Orbit's knowledge graph to make intelligent, context-aware deployment decisions.

Comment

InfraGuard AI - Hackathon Submission

Inspiration

As DevSecOps engineers, we've lived the pain of infrastructure promotion decisions. Teams run excellent tools—Checkov finds security issues, Trivy catches vulnerabilities, Infracost estimates costs—but the critical question remains unanswered: "Is this change safe to promote?"

The answer requires correlating evidence from 5+ different tools with context scattered across GitLab: approval status, CODEOWNERS, historical failure rates, related incidents, and linked change records. This information already exists in GitLab Orbit's knowledge graph, but no one was using it to make intelligent governance decisions.

When we discovered the GitLab Transcend Hackathon's focus on Orbit, we saw the opportunity to build something transformative. Instead of just displaying Orbit data, we could use it to change deployment decisions and automate the most time-consuming part of infrastructure governance.

What it does

InfraGuard AI is an intelligent promotion governance agent that turns scattered evidence into actionable deployment decisions.

The workflow is simple:

  1. Developer mentions the agent in a merge request:

    @ai-infraguard-promotion-governance evalúa esta promoción

  2. InfraGuard analyzes the change by:

    • Reading CI pipeline evidence (Terraform, Checkov, Trivy, Infracost, OPA)
    • Querying GitLab Orbit's knowledge graph (token-less via glab orbit remote query)
    • Extracting security findings directly from Orbit Finding entities
    • Pulling MR context, approvals, ownership, and historical data

  3. The deterministic engine calculates:

    • Risk score (0-100) based on findings severity, IaC changes, and Orbit context
    • Environment-specific decision (APPROVE, NEEDS_APPROVAL, or BLOCK)
    • Required actions grouped by role (security, owner, platform, maintainer)

  4. InfraGuard publishes:

    • Executive summary as MR comment with clear decision and evidence
    • One GitLab issue per finding with rich context and next steps
    • Complete audit trail for compliance

The key innovation: Same technical evidence + different Orbit context = different decisions. Our demo shows MR !42 blocked (no approvals, recent incident) and MR !43 approved (all approvals present, documented exception), despite identical security findings.

How we built it

Architecture

We designed InfraGuard with clean separation of concerns:

Evidence Collection → Correlation → Governance → Output
         ↓
   Orbit Remote Client (token-less)

Key components:

  1. Evidence Adapters - Normalize outputs from Terraform, Checkov, Trivy, Infracost, OPA into a common model
  2. Orbit Remote Client - Uses glab orbit remote query (token-less) to access the knowledge graph
  3. Correlation Engine - Enriches technical evidence with Orbit context
  4. Governance Engine - Deterministic risk scoring and policy-based decisions
  5. Output Layer - Markdown reports and GitLab issue creation

Technical Implementation

Orbit Integration (the breakthrough):

class OrbitRemoteClient:
    def _query_orbit(self, query: str):
        # Token-less operation under user identity
        result = subprocess.run([
            "glab", "orbit", "remote", "query",
            "--project-id", self.project_id,
            "--query", query
        ], capture_output=True, text=True)
        return json.loads(result.stdout)

Hybrid evidence architecture:

  • From Orbit: Security findings (when Checkov uses -o gitlab_sast), CI jobs, historical failure rates
  • From Artifacts: Terraform plan details (Orbit doesn't index plans yet)
  • This hybrid approach maximizes what Orbit provides while filling gaps

Risk scoring algorithm:

risk = sum(severity_points for findings)
     + (deletes × 6) + (replacements × 10)
     + (20 if critical_component else 0)
     + (10 if shared_components else 0)
     + (12 if recent_incidents else 0)
     + int(failure_rate × 40)
     - (40 if documented_exception else 0)

return min(risk, 100)

Environment-specific policies:

  • Development: max_risk=80, no blocking on CRITICAL
  • UAT: max_risk=65, blocks on CRITICAL
  • Staging: max_risk=55, requires linked issues for high risk
  • Production: max_risk=40, strict approval requirements

Development Process

  1. Week 1-2: Research Orbit capabilities, design architecture, build evidence adapters
  2. Week 3: Implement Orbit Remote client, discover Finding entities integration
  3. Week 4: Build governance engine, implement risk scoring and policies
  4. Week 5: Polish output format, add automatic issue creation, comprehensive testing
  5. Final push: 61 unit tests, documentation, demo environment

Tech stack:

  • Python 3.11+ (core engine)
  • GitLab Duo Agent Platform (Flow orchestration)
  • GitLab Orbit Remote (glab CLI for knowledge graph access)
  • GitLab REST & GraphQL APIs
  • Standard library (unittest, subprocess, json, hashlib)

Challenges we ran into

Challenge 1: Understanding Orbit's Security Findings

Problem: Initially, we thought security findings only existed as CI artifacts. How could Orbit help?

Discovery: When Checkov runs with -o gitlab_sast output format, findings are indexed as Orbit Finding entities! We could query them directly through Orbit's GraphQL interface.

Solution: Built queries to fetch findings filtered by project, scanner, and MR:

query {
  findings(
    projectId: {equals: 12345},
    scannerName: {equals: "checkov"}
  ) {
    nodes { id, name, severity, description, location }
  }
}

Challenge 2: Token-less Authentication

Problem: How to access Orbit without managing tokens in the Flow runtime?

Solution: Discovered glab orbit remote query runs under the authenticated user's identity. No token management needed! This was perfect for governance flows where the agent acts on behalf of the user.

Challenge 3: UAT Blocking Logic Bug

Problem: During testing with real data, discovered UAT environment with risk 100/100 showed NEEDS_APPROVAL instead of BLOCK.

Root cause: Blocking condition only checked environment in {"staging", "production"} but excluded "uat".

Fix: Added UAT to the blocking condition:

if risk_score > max_risk and environment in {"uat", "staging", "production"}:
    decision = BLOCK

Updated tests, all 61 now passing.

Challenge 4: Issue Creation at Scale

Problem: With 14 security findings, we needed to create 14 GitLab issues without:

  • Creating duplicates on re-run
  • Failing if labels don't exist
  • Overwhelming developers with poor descriptions

Solution: Implemented triple-fallback strategy:

try:
    # Attempt 1: Create with all labels
    issue = client.create_issue(title, description, labels=[base, role, category])
except:
    try:
        # Attempt 2: Create with base label only
        issue = client.create_issue(title, description, labels=[base])
    except:
        # Attempt 3: Create without labels
        issue = client.create_issue(title, description)

Added deduplication by title prefix (first 50 chars) and rich markdown descriptions with MR context and next steps.

Challenge 5: Output Readability

Problem: Initial output was text-heavy and hard to scan. Judges and developers need quick insights.

Solution: Complete redesign:

  • Visual hierarchy (markdown headers, emojis: ✅⚠️🚫)
  • Dedicated "GitLab Orbit Context" section with badge
  • Grouped findings (Security & Compliance, Approvals, Policy)
  • Smart truncation (show top items, indicate total)
  • Clear required actions by role

Challenge 6: Hybrid Architecture Design

Problem: Orbit doesn't index Terraform plan JSON yet, but we need IaC change details.

Solution: Built hybrid approach:

  • Query Orbit for: security findings, CI jobs, pipeline history, MR context
  • Read artifacts for: Terraform plan changes, replacements, deletes
  • Gracefully degrade if artifacts unavailable (don't fail hard)

This maximizes Orbit usage while being practical about current capabilities.

Accomplishments that we're proud of

1. Real Orbit Integration (Not Just Display)

We don't just show Orbit data—we use it to change decisions. MR !42 and !43 have identical technical evidence but different Orbit context, resulting in BLOCK vs. APPROVE decisions. This demonstrates meaningful Orbit usage per hackathon requirements.

2. Token-less Operation

Using glab orbit remote query under user identity means zero token management. No secrets, no OAuth complexity, no security risk. Just works.

3. Production-Ready Quality

  • ✅ 61 unit tests passing (adapters, correlation, governance, output)
  • ✅ Comprehensive error handling and graceful degradation
  • ✅ Complete documentation (README, code comments, examples)
  • ✅ Real-world demo with actual IaC repository

4. Complete Automation

From finding to resolution:

  1. Security finding detected in Orbit
  2. InfraGuard calculates risk and decision
  3. MR comment posted with explanation
  4. GitLab issue created with rich context
  5. Assigned to appropriate role via CODEOWNERS

Zero manual steps. Complete audit trail.

5. GitLab-Native UX

No custom UI built or maintained. Uses GitLab's native features:

  • Merge request comments (decision output)
  • GitLab issues (tracking)
  • Labels (routing)
  • Assignments (CODEOWNERS)
  • AI Catalog Flow (distribution)

6. Deterministic + AI Architecture

The deterministic engine makes decisions (auditable, explainable, predictable). AI/LLM only orchestrates workflow and explains results. This builds trust and meets compliance requirements.

7. Solved Real DevSecOps Pain

Reduces promotion decision time from ~30 minutes (review 5 tools manually) to ~2 minutes (read one comment). That's a 93% time reduction per merge request.

What we learned

Technical Learnings

  1. GitLab Orbit is incredibly powerful - The knowledge graph provides context that individual tools simply cannot access. Historical failure rates, related incidents, and component criticality transform governance decisions.

  2. Token-less is the future - glab orbit remote query running under user identity is genius for governance. No token management means no security risks and simpler deployments.

  3. Hybrid approaches are pragmatic - Orbit doesn't index everything yet (e.g., Terraform plans), but combining Orbit knowledge graph with targeted artifact access gives best results.

  4. Finding entities are underutilized - Most teams don't know that -o gitlab_sast creates queryable Finding entities in Orbit. This is a game-changer for security governance.

  5. Deterministic + AI is the right split - Having the deterministic engine make decisions while AI orchestrates and explains builds trust. Stakeholders can audit the logic.

Design Learnings

  1. GitLab as the UI works - Using MR comments and issues means zero UI development while providing familiar, integrated UX.

  2. Environment-specific policies are essential - Development can tolerate risk 80/100, but production needs <40. One-size-fits-all governance fails.

  3. Developers need next steps - Rich issue descriptions with "what to do" increased adoption. Just listing findings doesn't help.

  4. Deduplication is critical - Without it, re-running InfraGuard creates spam. Title-prefix matching solved this elegantly.

  5. Visual hierarchy matters - Emojis (✅⚠️🚫), headers, and grouped sections made output scannable. First iteration was text walls that no one read.

Process Learnings

  1. Test-driven development pays off - 61 tests caught the UAT blocking bug before demo. Refactoring was confident and fast.

  2. Real data beats mocks - Testing with actual Orbit Finding entities revealed edge cases we never imagined.

  3. Documentation is a feature - Comprehensive README with examples made testing and demos smooth. Future judges/users will appreciate it.

GitLab Orbit Learnings

  1. Orbit Remote is production-ready - glab orbit remote query is stable, fast (<200ms queries), and reliable
  2. GraphQL schema is well-designed - Filtering by project, scanner, severity works intuitively
  3. Historical data unlocks intelligence - Failure rates and incident correlation are governance gold
  4. Component criticality is underused - Teams should tag critical components in Orbit; governance can automatically increase scrutiny

What's next for InfraGuard AI - Orbit-Powered IaC Governance

Immediate (Post-Hackathon)

1. Enhanced LLM Explanation Layer

  • Natural language summaries of decisions
  • Conversational Q&A about findings
  • Suggested remediation steps with code examples

2. Custom Policy Configuration

  • YAML-based policies (not hardcoded Python)
  • Per-project policy overrides
  • Policy versioning and audit

3. Multi-IaC Support

  • Pulumi (TypeScript/Python state analysis)
  • Kubernetes manifests (kubectl diff integration)
  • Helm charts (values validation)
  • Ansible playbooks
  • CloudFormation templates

Short-term (3-6 months)

4. Compliance Framework Alignment

  • SOC2 control mapping
  • ISO27001 evidence collection
  • NIST Cybersecurity Framework
  • CIS Benchmarks validation
  • Automatic compliance reporting

5. Advanced Orbit Integration

  • Query code ownership history
  • Analyze commit patterns (frequent late-night commits = risk?)
  • Track exception expiration dates
  • Monitor policy violation trends

6. Integration Ecosystem

  • Slack notifications for critical promotions
  • Jira ticket creation for remediation
  • PagerDuty integration for incident correlation
  • ServiceNow change records

7. Analytics Dashboard

  • Governance metrics over time
  • Risk score trends by component
  • MTTR (Mean Time To Remediate) tracking
  • Approval bottleneck identification
  • Cost impact visualization

Long-term (6-12 months)

8. GitLab Compliance Framework Integration

  • Native compliance framework enforcement
  • Custom approval rules based on findings
  • Separation of duties validation
  • Automatic audit log generation

9. Advanced Risk Modeling

  • Machine learning for risk prediction
  • Component dependency risk propagation
  • Blast radius calculation
  • Rollback risk assessment

10. Self-Service Policy Studio

  • Visual policy builder for non-programmers
  • Policy simulation ("what-if" analysis)
  • A/B testing for policy changes
  • Community policy sharing

11. Multi-Cloud & Multi-Tenant

  • AWS, Azure, GCP support
  • Multi-region deployment governance
  • Tenant isolation validation
  • Cross-cloud resource tracking

12. Continuous Governance

  • Runtime drift detection
  • Scheduled re-evaluation of deployed resources
  • Automatic remediation workflows
  • Compliance posture monitoring

Vision

We envision InfraGuard evolving into the governance layer for GitLab Orbit—a platform where every infrastructure change is evaluated against organizational policies, historical context, and real-time risk, with complete automation from detection to resolution.

The ultimate goal: Zero-touch infrastructure promotion for low-risk changes, with automatic escalation and remediation workflows for high-risk scenarios, all powered by GitLab Orbit's knowledge graph.

Built With

  • checkov
  • cicd
  • gitlab
  • orbit
  • python
  • terraform
Share this project:

Updates