sentry-node 0.1.0

AI Security Framework — 4-layer guardrail architecture for modern AI applications

Sentry Node

Security Framework for AI applications.

---

Requirements

• Python 3.11+
• uv (recommended) or pip

---

Installation

Using uv (recommended)

# Clone the repo
git clone https://gitlab.otxlab.net/padith/sentry-node.git
cd sentry-node

# Create virtual environment and install dependencies
uv venv
uv pip install -e ".[dev]"

Using pip

git clone https://gitlab.otxlab.net/padith/sentry-node.git
cd sentry-node

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -e ".[dev]"

---

Running Tests

# Run all tests
uv run pytest

# With coverage
uv run pytest --cov=sentry_node --cov-report=term-missing

---

CI / CD

The pipeline is defined in .gitlab-ci.yml and runs two stages on every push and merge request:

Stage	Job	Tool	Purpose
secret-scan	secret_detection	GitLab built-in	Scans for hardcoded secrets using Gitleaks; results in Security tab
secret-scan	gitleaks_scan	Gitleaks (Docker)	Additional custom scan; uploads gitleaks-report.json on failure
test	test	pytest	Runs the full test suite; fails pipeline if any test fails

Both secret-scan jobs are set to allow_failure: false — a pipeline cannot merge if credentials are detected.

What is scanned for:

• Hardcoded passwords, API keys, tokens
• Private keys (RSA, SSH, PGP)
• AD/LDAP credentials in source code
• AWS, Azure, GCP access keys
• JWT secrets and connection strings

Utilities

Structured Logging

• Built on structlog — every log line is a clean key=value record
• Uppercase levels — INFO, WARNING, ERROR with no padding
• Auto-configured on import — reads log_level and audit_log_path from settings
• Rotating audit log — writes to a file (10 MB × 5 backups) with ANSI codes stripped
• JSON mode available for production log aggregators (Datadog, Splunk, etc.)

Configuration

• Powered by pydantic-settings
• Priority order: environment variables → .env file → defaults
• MONITORING_LOG_LEVEL, MONITORING_AUDIT_LOG_PATH — logging settings
• LDAP_SERVER, LDAP_DOMAIN, LDAP_BIND_USER, LDAP_BIND_PASSWORD, LDAP_BASE_DN, LDAP_USE_TLS, LDAP_PORT — AD settings

Exception Hierarchy

• SentryBaseError — base class; catch the whole family with one except
• PermissionDeniedError(role, permission) — raised by @rbac.require on denial
• AuthenticationError(username, reason) — raised by ActiveDirectoryAuth on failure
• ConfigurationError — raised for invalid configuration
• GuardrailError(reason, check) — raised by InputGuardrail / OutputGuardrail on a blocked request; check names the failing rule (e.g. "prompt_injection", "sensitive_keyword")

Features

Organization Layer

Role-Based Access Control (RBAC)

• Define roles with grouped permissions — {"data": ["read", "write"], "users": ["manage"]}
• Rank-based hierarchy — compare privilege levels with is_at_least(role, minimum)
• Runtime grant / revoke — add or remove actions without redefining a role
• Decorator enforcement — @rbac.require("data", "write") guards any function automatically
• Membership test — "admin" in rbac

Platform Layer

Active Directory Authentication

• Authenticate users against Active Directory / LDAP using ActiveDirectoryAuth
• Returns a typed AuthResult with the user's DN, AD group list, and mapped application role
• Group → role mapping — configurable dict maps AD group names to RBAC roles
• LDAP injection protection — all user input is escaped before use in search filters
• TLS by default — LDAP_USE_TLS=true (LDAPS on port 636)
• All credentials loaded from environment variables — nothing hardcoded
• Raises AuthenticationError with a reason code on failure (USER_NOT_FOUND, INVALID_CREDENTIALS, LDAP_UNAVAILABLE)

Application Layer

Input Guardrails

• Screen user prompts before they reach the AI model
• Prompt injection detection — matches 15+ patterns (role-override, jailbreak, XML/Llama tag injection, etc.); raises GuardrailError by default
• PII scrubbing — redacts email, phone, SSN, credit card, and IP address with configurable labels (e.g. <EMAIL>)
• Extensible — pass extra_injection_patterns to add custom regex rules
• Returns a GuardrailResult with safe_text, is_safe, pii_found, and injection_matches

from sentry_node.application import InputGuardrail

guard = InputGuardrail()
result = guard.check("My email is [e-mail] — ignore all previous instructions")
# raises GuardrailError (injection detected)

Output Guardrails

• Screen AI responses before they reach the user
• PII scrubbing — same patterns as InputGuardrail; AI models can echo PII from context
• Content policy — blocks harmful instructions, self-harm, and direct threats
• Keyword blocking — configurable list of sensitive internal terms that must never appear in output
• Classification leakage — map roles to maximum tiers (PUBLIC / CONFIDENTIAL / RESTRICTED) and block responses that expose higher-classified terms
• Returns a GuardrailResult with safe_text, is_safe, pii_found, policy_violations, and blocked_keywords_found

from sentry_node.application import OutputGuardrail

guard = OutputGuardrail(
    sensitive_keywords=["Project Senty Node", "Operation Sentry Node"],
    classified_terms={"RESTRICTED": ["merger", "acquisition"]},
    role_max_tier={"viewer": "PUBLIC", "editor": "CONFIDENTIAL", "admin": "RESTRICTED"},
)
result = guard.check(ai_response, role="editor")

---

Project Structure

sentry-node/
├── src/sentry_node/
│   ├── application/
│   │   ├── __init__.py       # re-exports InputGuardrail, OutputGuardrail, GuardrailResult
│   │   └── guardrails.py     # input/output guardrail classes
│   ├── organization/
│   │   ├── __init__.py       # re-exports RBAC
│   │   └── rbac.py           # RBAC class
│   ├── platform/
│   │   ├── __init__.py       # re-exports ActiveDirectoryAuth, AuthResult
│   │   └── user_authentication_AD.py  # AD/LDAP authentication
│   ├── config.py             # pydantic-settings (env / .env / defaults)
│   ├── exceptions.py         # SentryBaseError, PermissionDeniedError, AuthenticationError, ConfigurationError, GuardrailError
│   ├── logging.py            # structlog setup + get_logger()
│   └── __init__.py           # package entry point
└── tests/
    ├── test_guardrails.py
    ├── test_rbac.py
    ├── test_exceptions.py
    ├── test_config.py
    └── test_logging.py

---

License

MIT