Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Keep root-context builds (prompt-advisor) from shipping the whole repository.
# Without this the build context includes every module's target/ directory,
# which is several GB of jars.
**/target/
.git/
**/node_modules/
**/.venv/
**/__pycache__/
*.jar
docker/
ops-scripts/
sentrius-chart/
sentrius-chart-launcher/
!prompt-advisor/**
4 changes: 2 additions & 2 deletions .gcp.env
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
SENTRIUS_VERSION=1.1.161
SENTRIUS_VERSION=1.1.162
SENTRIUS_SSH_VERSION=1.1.13
SENTRIUS_KEYCLOAK_VERSION=1.1.16
SENTRIUS_AGENT_VERSION=1.1.76
SENTRIUS_AGENT_VERSION=1.1.82
SENTRIUS_AI_AGENT_VERSION=1.1.65
LLMPROXY_VERSION=1.1.22
LAUNCHER_VERSION=1.1.12
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -69,3 +69,7 @@ docker/prompt-advisor/prompt-advisor
# Python
*.pyc
__pycache__/

# Rendered Helm output - may contain resolved Secret values
rendered*.yaml
ops-scripts/**/rendered-*.yaml
173 changes: 173 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Sentrius is a zero trust security platform for protecting infrastructure — SSH sessions, APIs, and RDP connections — with AI-powered monitoring, dynamic policy enforcement, and self-healing capabilities. It is a Java 17 / Spring Boot 3.4.x multi-module Maven project with a secondary Python agent framework.

## Build Commands

**CRITICAL: Builds take ~7 minutes, tests ~1 minute. NEVER cancel builds or tests. Use 60+ minute timeouts.**

```bash
# Full build (7m24s first time, 3-5min cached)
mvn clean install

# Build without tests (faster for dev)
mvn clean install -DskipTests

# Build specific module with dependencies
mvn clean install -pl api -am
mvn clean install -pl core,api,dataplane -am

# Run all tests (~1m3s)
mvn test

# Run tests for a single module
mvn test -pl api
mvn test -pl core

# Run a single test class
mvn test -pl api -Dtest=DocumentControllerTest

# CI equivalent
mvn -B package --file pom.xml
```

### Helm Chart Validation
```bash
helm lint sentrius-chart
helm lint sentrius-chart-launcher
helm template test-launcher sentrius-chart-launcher --set tenant=test-tenant --dry-run
```

### Python Agent
```bash
cd python-agent
pip3 install -r requirements.txt
TEST_MODE=true python3 main.py chat-helper --task-data '{"test": "message"}'
```

### Docker Images
```bash
./ops-scripts/base/build-images.sh --all --no-cache # Sequential
./ops-scripts/base/build-all-images-concurrent.sh --all --no-cache # Parallel (faster)
```

## Architecture

### Module Dependency Graph

```
provenance-core (standalone: event tracking/audit)
core (sentrius-core) (business logic, JPA entities, repositories, services)
dataplane (data processing, depends on core + sag)
llm-core → llm-dataplane (LLM integration layers, depend on core)
api (REST API + web UI, depends on core/dataplane/llm-*)
integration-proxy (external service proxy, adds Kubernetes client)
agent-proxy (agent communication proxy)
agent-launcher (K8s pod lifecycle management)
analytics (AI-powered monitoring/analysis agent)
enterprise-agent (AI enterprise agent)
monitoring (system monitoring agent)
ssh-proxy / ssh-agent (SSH proxy and agent)
rdp-proxy (RDP proxy)
provenance-ingestor (Kafka event ingestion)
sag (ANTLR4 grammar for agent rules/guardrails, standalone)
```

### Spring Boot Applications (12 runnable services)
- **api** (port 8080) — Main REST API and web UI
- **integration-proxy** — External service integrations (LLM, GitHub, JIRA)
- **agent-proxy** — WebSocket-based agent communication
- **agent-launcher** — Dynamic agent lifecycle via Kubernetes
- **analytics** — Java AI analysis agent (document relationships, session summarization, trust evaluation)
- **enterprise-agent** — AI-powered enterprise agent
- **monitoring** — System monitoring agent
- **ssh-agent** / **ssh-proxy** — SSH session handling
- **rdp-proxy** — RDP session handling
- **provenance-ingestor** — Event ingestion from Kafka

### Library Modules (not runnable)
- **provenance-core** — Event/audit model
- **core** — JPA entities, repositories, services, DTOs, security config
- **dataplane** — Data processing services (knowledge graph ingestion, system options)
- **llm-core** / **llm-dataplane** — LLM message models, categorization, response handling
- **sag** — Sentrius Agent Grammar (ANTLR4 DSL for guardrails/rules)

### Key Package Structure
Base package: `io.sentrius.sso`
- `core.model` — JPA entities (hosts, sessions, agents, documents, trust)
- `core.repository` — Spring Data JPA repositories
- `core.services` — Business logic services
- `core.dto` — Data transfer objects
- `core.config` — Configuration classes (SystemOptions for feature flags)
- `core.security` — Security configuration
- `controllers.api` — REST API controllers
- `automation` — Rule automation and auditing
- `genai` — Generative AI / LLM models
- `io.sentrius.agent.analysis` — Analytics agent implementations

### Data Stores
- **PostgreSQL** (required) — Primary relational store with pgvector for embeddings
- **Keycloak** (required) — OAuth2/OIDC authentication
- **Knowledge graph** (optional) — pluggable via `KnowledgeGraphPort`; no backend ships by default
- **Neo4j** (optional) — Graph analysis
- **Kafka** (optional) — Event streaming for provenance
- **Qdrant** (optional) — Vector search

### Database Migrations
Flyway migrations in `api/src/main/resources/db/migration/` (V1 through V36+). H2 in-memory database is used for tests.

### Key Architecture Patterns
- **ZTAT (Zero Trust Access Tokens)** — Custom token-based zero trust architecture
- **ABAC** — Attribute-Based Access Control
- **SAG** — ANTLR4-based DSL for agent guardrails (parsed in `sag` module, used by `dataplane`)
- **Self-healing** — Automatic error detection and code repair via coding agents
- **Knowledge graph** — Document ingestion behind `KnowledgeGraphPort` with concept extraction for Q&A
- **MCP (Model Context Protocol)** — Integration with external tools (GitHub, coding)
- **Provenance** — Full audit trail via Kafka event streaming
- **WebSocket** — Real-time communication for terminals, agent status, monitoring

## Local Development Environment

Default service endpoints:
- PostgreSQL: `home.guard.local:5432` (database: `sentrius`, user: `postgres`)
- Keycloak: `http://localhost:8180`
- OpenTelemetry: `http://localhost:4317`

Key environment variables: `KEYCLOAK_BASE_URL`, `KEYCLOAK_SECRET`, `DATABASE_PASSWORD`, `KEYSTORE_PASSWORD`, `BASE_URL`

Running locally:
```bash
./ops-scripts/local/run-sentrius.sh --build # convenience script
# OR
cd api && mvn spring-boot:run # direct (needs PostgreSQL + Keycloak)
```

## Build Warnings (Safe to Ignore)

```
'dependencyManagement.dependencies.dependency' must be unique: org.projectlombok:lombok:jar
'dependencyManagement.dependencies.dependency' must be unique: org.springframework.boot:spring-boot-starter-web:jar
'dependencies.dependency' must be unique: org.springframework.boot:spring-boot-starter-actuator:jar
```

## Non-Maven Components

- **python-agent/** — Python 3.12+ agent framework (chat-helper, mcp, coding, knowledge-graph agents)
- **sentrius-chart/** — Helm chart for full Kubernetes deployment (70+ templates)
- **sentrius-chart-launcher/** — Lightweight Helm chart for agent launcher only
- **ops-scripts/** — Deployment scripts organized by environment (local, gcp, azure)
- **docker/** — 17 Dockerfiles for all services (base image: eclipse-temurin:17-jdk-noble)

## CI/CD

GitHub Actions workflows in `.github/workflows/`:
- **maven.yml** — Java build + tests on push/PR to main (JDK 17 temurin)
- **helm-ci.yml** — Helm linting, template rendering, schema validation, integration tests with kind cluster
Loading
Loading