CascadeAgent

• 

Inspiration

What it does

CascadeAgent is a GitLab Duo Agent Platform tool that solves a critical security workflow problem: when a vulnerable dependency is found in one project, finding every other affected project and coordinating remediation across the organization is slow, manual, and error-prone.

You run one command: python scripts/run_cascade.py lodash my-project --version 4.17.15 --severity critical

CascadeAgent then:

1. Queries GitLab Orbit — the organization-wide knowledge graph — to find every project using the vulnerable package
2. Resolves the responsible owner for each project via Orbit's ownership graph
3. Creates a parent Cascade Report work item in the source project
4. Creates a child remediation work item in every affected project, assigned to its owner
5. Updates the parent report with a full summary table linking everything

What took hours of manual searching now takes seconds.

How we built it

Built entirely in Python with FastAPI, httpx, and Pydantic v2. The project has three layers:

• Orbit client (orbit_client.py): queries GitLab Orbit's knowledge graph at /api/v4/orbit/ using the schema's Project, ImportedSymbol, Finding, and User node types with MEMBER_OF, IMPORTS, and IN_PROJECT edges
• GitLab GraphQL client (gitlab_client.py): creates Work Items, assigns users, and links parent/child items via the workItemCreate and workItemUpdate mutations
• Cascade service (cascade_service.py): orchestrates the full workflow — Orbit query → plan → GitLab writes — with per-project error isolation so a failure in one project never stops remediation in the others

The system is fully async (asyncio + httpx) and designed so every component is independently testable. 8 unit tests pass against mocked HTTP.

How we used GitLab Orbit

Orbit is central to CascadeAgent — the entire project exists because Orbit makes cross-project questions answerable.

Specifically we use:

• /api/v4/orbit/status — health check confirming Orbit is live before each run
• /api/v4/orbit/schema — read at startup to understand available node types and edges
• /api/v4/orbit/query — traversal queries using Project, ImportedSymbol, Finding, and User nodes with IMPORTS, HAS_FINDING, and MEMBER_OF edges to find affected projects and resolve owners

The Orbit query DSL (query_type: traversal/aggregation/neighbors) is experimental and the exact format was discovered during the hackathon by reading schema error messages. A GitLab REST fallback handles cases where Orbit returns no results, ensuring the automation works end to end.

Challenges

The biggest challenge was discovering the exact Orbit query format. The DSL requires a query object with a query_type field accepting values like "traversal", "aggregation", or "neighbors" — none of which is publicly documented. We reverse-engineered this from schema validation error messages during the hackathon.

The second challenge was GitLab's Work Item hierarchy constraints: Epic→Issue hierarchy works in group namespaces but not personal namespaces used for the demo. We adapted by using Issue as parent and Task as children with description-based linking.

What we learned

GitLab Orbit is genuinely powerful — having a queryable graph of the entire SDLC means questions that previously required custom scripts crawling every repo individually become single API calls. The schema exposes 27 node types and 50+ edge types covering everything from source code structure to security findings to CI/CD pipelines.

What's next

• Correct Orbit query DSL once documented: swap the REST fallback for real graph traversal
• Webhook trigger: fire automatically when GitLab security scanner creates a new finding
• Auto-generated remediation MRs: not just creating the ticket but opening the actual fix
• Publish to AI Catalog as a public Flow so any GitLab organization can install it

Built with

Python, FastAPI, httpx, Pydantic v2, GitLab GraphQL API, GitLab Orbit REST API, MCP (Model Context Protocol), GitLab Duo Agent Platform

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for CascadeAgent

Built With

• fastapi
• gitlab
• graphql
• mcp
• orbit
• python