sentinelcore-ai - AI-powered defensive cybersecurity analysis platfo

项目说明

SentinelCore AI

AI-Powered Cybersecurity Analysis & Incident Response

SentinelCore AI is a full-stack, defensi Security Operations Center (SOC) support
platform. It combines deterministic security engineering - log parsing, URL/domain heuristics,
email header analysis, IOC , and a transparent scoring engine - with optional
multi-provider AI assistance (OpenAI, Anthropic Claude, Google Gemini) that features automatic
fallback, structured/ output, and prompt-injection resistance.

It is built to demonstrate real software engineering and cybersecurity fundamentals, not just
API calls to a language model: every deterministic finding is computed in Python and shown
separately from anything an AI model infers.

Built by Oleh Datsyk.

---

Table of Contents

Project O

Features

Architecture

Screenshots

Technology Stack

AI Pro

Cybersecurity Features

Installation

Local Usage

En

Render Deployment

API Endpoints

Security Considerations

Project Limitations

Future Impro

Author

---

Project O

SentinelCore AI simulates a lightweight, AI-assisted SOC. A user can submit security logs,
authentication logs, firewall/web server logs, suspicious URLs or domains, suspicious email
content and headers, IP addresses, file hashes, or free-text incident descriptions. The
application analyses the input, distinguishing clearly between:

Facts - objecti findings computed in Python (regex/parsing/heuristics).

Obser - patterns detected by the deterministic layer, presented as e.

AI Assessments - an optional AI model's structured, interpretation of the facts.

Recommendations - in steps and defensi, from either layer.

The AI layer ne uncertain information is confirmed, and the application remains
fully functional - including logging, scoring, incident management, and reporting - with
zero AI pro configured.

Features

Uni Security Analyzer (deterministic pre-processing + optional AI)

Security Log Analyzer with authentication-specific deep analysis

Phishing Email Analyzer with safe, static email header parsing (SPF/DKIM/DMARC)

URL & Domain Analyzer (ne the submitted URL - string analysis only)

IOC Analyzer & tracker (IPv4/IPv6/domain/URL/MD5/SHA-1/SHA-256)

Incident Management with a full timeline, notes, and e

AI Incident Triage with an explicit "Accept Recommendation" step (ne)

AI Security Analyst - answers grounded in stored data, not a generic chatbot

Defensi Engine (5 built-in automations) with a full run log

Report Generator (Incident / Security Analysis / Phishing / IOC / Executi)

Analytics dashboard dri by real stored data (no fabricated numbers)

Multi-provider AI status page with per-provider connectivity testing

Safe, clearly-labelled demo data loader

Architecture

Design principle: deterministic analysis (Python) and AI assessment are always kept
separate in both the data model and the UI. AI is used only for the interpretive work Python
cannot reliably do itself - not for things like URL parsing or regex-based log pattern
detection, which are computed directly.

Screenshots

_Add screenshots of the Dashboard, Security Analyzer, Incident detail view, and Analytics page
here after your first local run - e.g. docs/screenshot-dashboard.png._

Technology Stack

Backend: Python 3.11+, FastAPI, U, Pydantic v2, SQLAlchemy 2.x, python-doten
Database: SQLite (local default) - swappable to PostgreSQL via DATABASE_URL
Frontend: HTML5, CSS3, Ja (no frameworks, no Node.js, no build step)
AI: OpenAI, Anthropic Claude, Google Gemini - called directly via httpx REST requests

AI Pro

Configure any combination of the three supported pro . The
application:

Works with zero, one, two, or three pro configured.

In Automatic mode, tries each configured provider in order (OpenAI -> Claude -> Gemini by

default) until one succeeds, and reports which provider was used and whether fallback
occurred.

every AI response against a strict Pydantic schema. Malformed JSON triggers a

parsing-recovery attempt, and if that fails, falls through to the next provider.

Ne if all pro fail - it returns a clear, safe error and (where applicable)

falls back to deterministic-only analysis.

Cybersecurity Features

See SECURITY.md for the full defensi, responsible-use notes, and AI
limitations. In short: this project analyses and explains security-relevant information - it
does not exploit, attack, scan, or evade anything.

Installation

Requirements

Python 3.11 or newer

(Optional) API key(s) for OpenAI, Anthropic, and/or Google Gemini

Quick Start (Windows)

1. Download/extract the project.
2. Double-click Start App.bat.
3. The script creates a en, installs dependencies, creates .env from
.en if needed, starts the server, and opens automatically.

Quick Start (macOS)

1. Download/extract the project.
2. In Terminal: chmod +x "Start App (Mac).command"
3. Double-click Start App (Mac).command in Finder (or run it from Terminal).
4. The script performs the same steps as the Windows launcher and opens your default browser.

Manual Setup (any OS)

Then open

See INSTRUCTION.md for a complete, beginner-friendly walkthrough.

Local Usage

Once running, use the sidebar to na between the Dashboard, the fi (Security,
Log, Phishing, URL, IOC), Incidents, AI Security Analyst, Automations, Reports, Analytics, AI
Pro, and Settings. Use Load Demo Data in the top bar to populate the dashboard with
safe, clearly-labelled fictional records.

En

All are optional except where noted. Copy .en to .env and fill in what
you need.

| | Required | Description |
|---|---|---|
| OPENAI_API_KEY | No | Enables OpenAI as an AI provider |
| ANTHROPIC_API_KEY | No | Enables Anthropic Claude as an AI provider |
| GEMINI_API_KEY | No | Enables Google Gemini as an AI provider |
| OPENAI_MODEL | No | Defaults to gpt-4o-mini |
| ANTHROPIC_MODEL | No | Defaults to claude-3-5-sonnet-20241022 |
| GEMINI_MODEL | No | Defaults to gemini-1.5-flash |
| DATABASE_URL | No | Defaults to local SQLite. Set to a PostgreSQL URL in production |
| THREAT_INTEL_PROVIDER / THREAT_INTEL_API_KEY | No | Reserved for optional external threat intel integration |
| EN | No | de or production |
| PORT | No (Render sets this automatically) | Local default is 8000 |
| MAX_INPUT_LENGTH, MAX_UPLOAD_SIZE_BYTES, RATE_LIMIT_*, AI_COOLDOWN_SECONDS | No | Abuse-protection tuning, sane defaults provided |

At least one AI provider key is required for AI-assisted analysis, AI triage, and the AI
Security Analyst. **No key is required for the application to run and provide full deterministic
cybersecurity functionality.**

Render Deployment

SentinelCore AI is a single Render Web Service - FastAPI serves both the REST API and the
static dashboard, so no separate frontend service is needed.

1. Push this repository to GitHub.
2. In Render, create a new Web Service from the repo (or use the included render.yaml
Blueprint).
3. Build Command: pip install -r requirements.txt
4. Start Command: u app:app --host 0.0.0.0 --port $PORT
5. Health Check Path: /api/health
6. Add en manually under En -> En (see table
above). None are required to deploy - the app runs with deterministic features only until
you add AI keys.
7. For persistent storage across deploys, add a Render PostgreSQL instance and set
DATABASE_URL to its connection string. Without it, SQLite is used, which resets on
redeploy on most Render plans.

Start App.bat and Start App (Mac).command are local-only launchers - Render does not
run them.

API Endpoints

Security Considerations

API keys are read only from en and are never sent to the frontend, logged,

or embedded in HTML/JS.

All AI-analysed content (logs, emails, URLs, incident text) is explicitly framed to the AI as

untrusted data, with an instruction not to follow anything that looks like an embedded
command - reducing prompt-injection risk.

The ser , fetches, or executes anything from a submitted URL, email link, or

uploaded file.

File uploads are restricted by extension and size, decoded as text only, and ne.

All AI responses are against strict Pydantic schemas before being trusted anywhere

in the application.

See SECURITY.md for the full policy.

Project Limitations

Deterministic heuristics (URL/domain/log/phishing) are signal-based, not proof of malicious

intent, and are explicitly labelled as such throughout the UI.

No external threat intelligence is integrated by default - the architecture supports it, but

it must be added deliberately, and the UI always states when it's not configured rather than
fabricating a reputation score.

SQLite on most Render free/starter plans does not persist across redeploys - use

DATABASE_URL with a managed Postgres instance for durable production data.

AI-assisted assessments are probabilistic and should not be treated as a definiti

- see SECURITY.md.

Future Impro

Real external threat intelligence integration (e.g. reputation lookups) behind the existing

THREAT_INTEL_PROVIDER / THREAT_INTEL_API_KEY configuration surface.

User authentication / role-based access control for multi-analyst deployments.

WebSocket-based li updates.

PDF report export.

Historical trend analytics (week-o / month-o).

Author

Oleh Datsyk

项目信息

开发语言：Python

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕AI-powered defensive cybersecurity analysis platform for security logs, phishing detection, IOC analysis, incident triage, threat assessment, and automated security workflows using OpenAI, Claude, and Gemini.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。