CodeSentinel

CodeSentinel turns dependency vulnerabilities into explainable, application-aware priorities using vulnerability intelligence, deterministic risk scoring, and AI-powered security explanations.

Comment

CodeSentinel

Inspiration

Modern applications depend on open-source packages, and those dependencies can introduce security vulnerabilities. Developers can use vulnerability scanners to discover these issues, but a list of findings does not always answer the most important question:

Which finding should I investigate first, and why does it matter in my application?

We wanted to build a practical tool that goes beyond simply reporting vulnerabilities. Our goal was to connect vulnerability evidence with the application's context and turn that information into a transparent, understandable security priority.

That idea became CodeSentinel.

What CodeSentinel Does

CodeSentinel is an explainable dependency-risk prioritization system for Python applications.

A developer provides a requirements.txt file. CodeSentinel:

  1. Parses the application's dependencies.
  2. Retrieves vulnerability intelligence from the OSV vulnerability database.
  3. Collects application context such as:
  • Production or Development environment
  • Internet-facing or not
  • Runtime or Development dependency
  • Application role such as Authentication, API, Database, or UI
    1. Calculates a deterministic 0–100 risk score.
    2. Assigns a priority level.
    3. Shows the evidence and risk drivers behind the decision.
    4. Uses AI to explain the result in developer-friendly language.

The central principle of the system is:

AI explains. The Risk Engine decides. Evidence supports the decision.

The AI is therefore not responsible for inventing or changing the numerical security decision.

How We Built It

We built CodeSentinel as a lightweight full-stack security application.

Architecture

requirements.txt
       |
       v
Dependency Parser
       |
       +--------------------+
       |                    |
       v                    v
OSV Vulnerability      Application
Intelligence           Context
       |                    |
       +---------+----------+
                 |
                 v
        Deterministic
          Risk Engine
                 |
                 v
          Risk Priority
                 |
                 v
        AI Explanation
                 |
                 v
       Security Dashboard

Technology Stack

  • Python
  • FastAPI
  • Jinja2 / HTML / CSS / JavaScript
  • OSV API
  • OpenAI-compatible AI API integration
  • Git / GitHub
  • PyPI dependency ecosystem

The backend separates dependency parsing, vulnerability lookup, vulnerability processing, risk calculation, and AI explanation into independent components.

This separation was important because it keeps the security decision logic deterministic and makes the system easier to test and extend.

Risk Intelligence

CodeSentinel does not treat every vulnerability as equally urgent.

The risk engine combines vulnerability severity with application context.

Conceptually:

Risk Priority =
f(Severity, Environment, Exposure, Dependency Scope, Application Role)

For example, the same vulnerability can receive a different contextual priority when it belongs to a production, internet-facing, runtime authentication component compared with a development-only dependency.

The system also records the individual risk drivers so that the developer can understand why a score was produced instead of receiving only a number.

The Role of AI

AI is used as an explanation layer, not as the security decision-maker.

The deterministic layer produces:

  • Risk score
  • Priority
  • Risk drivers
  • Vulnerability evidence

The AI layer can then:

  • Explain why the finding matters
  • Summarize the security situation
  • Provide developer-oriented guidance
  • Suggest what should be investigated next

The AI is explicitly instructed not to change the numerical score or priority.

If an AI provider is unavailable, CodeSentinel can still calculate and display the deterministic risk result using its fallback explanation path.

This separation was one of the most important design decisions in the project because security decisions should remain reproducible.

What We Learned

Building CodeSentinel taught us that security tooling is not only about finding vulnerabilities.

A useful security product also needs to answer:

What does this finding mean for this application?

We learned how to:

  • Work with a real vulnerability intelligence API.
  • Parse and process dependency information.
  • Design a deterministic risk-scoring system.
  • Separate security logic from AI-generated explanations.
  • Build a developer-facing security dashboard.
  • Handle unpinned dependencies and invalid input safely.
  • Design fallback behavior when external AI services are unavailable.
  • Test the system against different application contexts.
  • Think about security decisions in terms of evidence and explainability rather than only severity.

Challenges We Faced

One of the biggest challenges was deciding how AI should participate in the system.

It would have been easy to ask an LLM to generate a risk score, but that would make the result potentially inconsistent and difficult to reproduce.

Instead, we separated the responsibilities:

Deterministic Risk Engine → makes the decision

AI Explanation Engine → explains the decision

Another challenge was handling real-world dependency input. Requirements files can contain unpinned packages, comments, extras, unsupported formats, and malformed entries. We therefore added parsing and validation logic instead of assuming every input would be perfectly formatted.

We also had to make external vulnerability lookup failures and unavailable AI providers fail gracefully rather than preventing the entire application from functioning.

Finally, we had to balance functionality with hackathon time constraints. Rather than attempting to build a complete enterprise SCA platform, we focused on one clear workflow and made that workflow functional and understandable.

Current Prototype

The current prototype focuses on the PyPI/Python dependency ecosystem and requirements.txt input.

It provides:

  • Dependency analysis
  • Vulnerability intelligence through OSV
  • Application-aware risk scoring
  • Risk drivers and evidence
  • AI-generated explanations
  • Security dashboard
  • Graceful handling of unsupported or unpinned dependencies
  • AI fallback behavior

The project is intentionally focused rather than trying to support every package ecosystem.

Future Scope

The architecture can be extended in several directions:

  • Support for additional package ecosystems
  • Richer application and deployment context
  • Integration with developer workflows and CI/CD
  • More detailed dependency relationships
  • Additional vulnerability intelligence sources
  • More advanced remediation guidance

These are future extensions; the current prototype focuses on demonstrating the core decision-making workflow.

Why It Matters

Security teams and developers can already discover large numbers of vulnerability findings.

The harder problem is turning those findings into understandable, application-specific decisions.

CodeSentinel aims to make that decision process visible:

Vulnerability Evidence
        +
Application Context
        ↓
Deterministic Risk Decision
        ↓
AI Explanation
        ↓
Developer Action

Instead of stopping at:

"We found a vulnerability."

CodeSentinel aims to answer:

"Here is why it matters in this application, what evidence supports that decision, and what you should investigate first."

Built With

Share this project:

Updates

Submission history