SENTINEL

Demmo Video - https://youtu.be/gIZY1S3MIdg

SENTINEL is an async, read-only security agent for open-source repositories. It watches pull requests, package changes, workflow files, AI-agent configs, Slack/Jira approval context, and local findings, then turns that evidence into deterministic Discord and Slack alerts.

It is built for the Coral hackathon formula: real problem, multiple data sources, meaningful joins, working demo, and a clear story.

What Problem We Solve

Open-source maintainers now review more than code. A normal pull request can hide a leaked credential, a risky dependency, a workflow permission escalation, a poisoned AI-agent skill, or a GitHub Action typo that changes who gets trusted inside CI.

This is already happening:

• Vercel / Context.ai incident: attackers reportedly abused over-permissioned third-party AI access into Google Workspace, with stolen data allegedly listed for about USD 2M. Source: https://www.tomshardware.com/tech-industry/cyber-security/vercel-breached-after-employee-grants-ai-tool-unrestricted-access-to-google-workspace
• tj-actions/changed-files compromise: a trusted GitHub Action affected 23,000+ repositories and exposed CI/CD secrets in workflow logs. Source: https://arstechnica.com/information-technology/2025/03/supply-chain-attack-exposing-credentials-affects-23k-users-of-tj-actions/
• Nx S1ngularity attack: malicious npm packages were published after a GitHub Actions weakness led to token theft, turning developer tooling into a supply-chain blast radius. Source: https://nx.dev/blog/s1ngularity-postmortem

SENTINEL focuses on the maintainer gap: CI may pass, but the repository attack surface has changed.

What We Built

SENTINEL is a FastAPI service with:

• Signed GitHub webhook ingestion.
• DuckDB as the canonical local security database.
• JSONL mirrors so Coral can query SENTINEL data as read-only file-backed sources.
• Socket.dev or Phylum supply-chain enrichment.
• OSV.dev vulnerability enrichment.
• npm and PyPI package metadata enrichment.
• mcp-scan plus deterministic AI-agent skill poisoning checks.
• Deterministic scoring for release-risk vectors.
• Debounced Discord and Slack alert delivery with clickable evidence links.
• Jira and Slack approval context for human-in-the-loop review.
• A local dashboard for demo and triage.
• A role-gated Discord /sentinel command that maps natural language to fixed Coral SQL macros.

SENTINEL does not block CI. It watches, correlates, scores, and routes evidence fast.

How We Used Coral

Coral is the query layer.

SENTINEL writes operational data into DuckDB and mirrors queryable rows into runtime/coral-data/*.jsonl. The app-local Coral source spec at sentinel/sources/sentinel_findings.yaml exposes those JSONL files as Coral tables.

Natural language never becomes arbitrary SQL. Instead:

1. A user asks /sentinel query: are we safe to release?.
2. sentinel/coral/query.py maps that intent to a fixed macro file.
3. Coral executes the approved SQL macro, for example sentinel/coral/macros/vw_release_blockers.sql.
4. SENTINEL returns a concise security brief with evidence links.

This gives us meaningful joins over repo events, findings, approvals, tickets, package intelligence, and file-backed evidence without turning the LLM into a query author.

Connected Data Sources

Core demo sources:

• GitHub webhooks: pull requests, pushes, changed files, commit SHAs, actor identity.
• DuckDB: canonical SENTINEL findings and alert history.
• JSONL files: Coral-readable mirror of DuckDB tables.
• Socket.dev: package and supply-chain intelligence.
• OSV.dev: known vulnerability data.
• npm and PyPI registries: package age, postinstall scripts, source repository metadata.
• mcp-scan: AI-agent skill and MCP configuration scan results.
• Slack: alert delivery and approval convention.
• Jira: approval/change-ticket lookup.
• Discord: alert delivery and /sentinel query surface.

Optional / enterprise sources:

• Phylum for paid supply-chain intelligence.
• GitHub Teams/Enterprise audit log polling.
• Google Workspace Admin SDK audit logs.

Demo Attack Surfaces

Demo Video - https://youtu.be/gIZY1S3MIdg

Live demo PRs are available in chaitanyamedidar/sentinel-demo-repo:

• PR #1: supply-chain risk.
• PR #2: credential exposure in PR metadata.
• PR #3: poisoned AI-agent SKILL.md.
• PR #4: workflow permission escalation fixture.
• PR #5: CI exfiltration fixture.
• PR #6: GitHub Action typosquat fixture.

SENTINEL also includes dashboard demo scenarios for identity/audit vectors that are difficult to reproduce safely on GitHub Free.

Architecture

GitHub Webhooks
  -> FastAPI ingestor
  -> DuckDB canonical store
  -> JSONL mirror
  -> Coral source spec
  -> fixed Coral SQL macros
  -> deterministic scorer
  -> Discord / Slack / dashboard

Enrichment runs asynchronously and fail-open:

Socket / Phylum
OSV.dev
npm / PyPI
mcp-scan
Jira / Slack approval context

Setup

cd E:\Files\Projects\SENTINEL
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
uvicorn sentinel.main:app --reload --host 127.0.0.1 --port 8787

Dashboard:

http://127.0.0.1:8787/

Coral Setup

python -m sentinel.scripts.init_runtime
$env:SENTINEL_CORAL_DATA_DIR = "file:///E:/Files/Projects/SENTINEL/runtime/coral-data/"
coral source lint sentinel/sources/sentinel_findings.yaml
coral source add --file sentinel/sources/sentinel_findings.yaml
coral source test sentinel
coral sql --format json "$(Get-Content -Raw sentinel/coral/macros/vw_release_blockers.sql)"

Discord Slash Command

Register /sentinel:

.\.venv\Scripts\python.exe -m sentinel.scripts.register_discord_command

Example:

/sentinel query: are we safe to release?

The command is role-gated using DISCORD_SECURITY_ROLE_ID.

Slack Approval Convention

For SENTINEL to correlate approvals, messages in #security-approvals must follow:

Approved: @github_username

Free-form messages are treated as unapproved.

Verification

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m pip_audit -r requirements.txt
coral source lint sentinel\sources\sentinel_findings.yaml
coral source test sentinel

What's Next

• Persist richer evidence links for exact files and PR comments.
• Add GitHub Teams/Enterprise audit-log polling for full identity governance.
• Add Google Workspace Admin SDK audit ingestion for enterprise tenants.
• Add a hosted dashboard deployment profile.
• Add more provider adapters behind the same findings schema.
• Add release-note generation from Coral macro results.

Learning & Growth

I had never used Coral before this hackathon. I knew the problem I wanted to solve - supply-chain attacks against open-source repositories - but I had to learn where Coral should sit in the architecture.

The biggest early mistake was assuming Coral's bundled GitHub source exposed a github.audit_log table. It does not, and GitHub audit logs also require higher org access than GitHub Free provides. The fix was to create sentinel.audit_events, populated from signed GitHub webhooks, then mirror those rows into JSONL for Coral.

I also learned that Coral should stay as the read/correlation layer, not the write or dispatch layer. Python handles enrichment, scoring, Discord/Slack delivery, and provider APIs. Coral handles source specs and fixed SQL macros. Once that boundary was clear, the system became much easier to reason about.

The most important architectural insight was the LEFT JOIN absence pattern. A missing Slack approval, missing Jira ticket, or missing identity mapping can be detected as structured SQL evidence. That made Coral central to SENTINEL: it is not just a convenience layer, it is the correlation layer that turns separate sources into one security decision.

During the build, several practical issues changed the design:

• sentinel.audit_events replaced the unavailable github.audit_log table.
• DuckDB became the canonical write store, with JSONL mirrors for Coral.
• Discord and Slack writes stayed in Python because they are dispatch targets, not Coral sources.
• External enrichment was made fail-open so deterministic findings still alert if Socket, OSV, npm, PyPI, or mcp-scan fail.
• A 10-second debounce queue was added so multiple findings on one commit become one alert instead of hitting Discord rate limits.
• mcp-scan became event-driven when PRs touch SKILL.md, .cursor/rules, mcp.json, or agent config paths.

Research into recent open-source incidents also expanded the vector set. SENTINEL now includes checks for unsigned maintainer commits, CI exfiltration scripts, orphan package owner changes, first-time contributors targeting self-hosted runners, force-push after approval, and GitHub Action typosquatting.

If I rebuilt it, I would validate Coral source specs first, then build the application around those queryable tables. Source spec first, application code second.