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 alice@corp.com — 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")

RAG Document Guardrails

• Accepts uploaded PDF and DOCX files as paths, bytes, or binary streams
• Validates file signatures, compressed size, extracted size, and PDF page count
• Extracts PDF pages, Word paragraphs, and Word table rows with source locations
• Groups adjacent small paragraphs under their DOCX heading and splits at heading boundaries
• Keeps table rows intact unless a row exceeds the configured token budget
• Splits oversized sections by model tokens with configurable token overlap
• Attaches source, heading, page, section type, token count, and safety metadata
• Applies injection, secrets, PII, homoglyph, and content-policy checks to each chunk
• Returns normalized and redacted chunks suitable for embedding and vector indexing
• Rejects encrypted, malformed, unsupported, oversized, and image-only documents

from sentry_node.application import DocumentGuardrail

guard = DocumentGuardrail(
    block_on_unsafe=False,
    chunking_strategy="advanced",
    chunk_size=500,      # model tokens, not characters
    chunk_overlap=50,
)

# Typical web upload: uploaded_file contains bytes and filename is user supplied.
result = guard.check(uploaded_file, filename="knowledge-base.pdf")

for chunk in result.chunks:
    vector_store.add(
        text=chunk.safe_text,
        metadata=chunk.metadata,
    )

Use block_on_unsafe=True (the default) to reject a document containing an injection, secret, homoglyph, or content-policy violation. PII is redacted in safe_text. Image-only PDFs require OCR before calling DocumentGuardrail.

Choose the chunking strategy when constructing the guardrail:

# Preserves DOCX headings, paragraph groups, table rows, and PDF pages.
advanced = DocumentGuardrail(chunking_strategy="advanced")

# Flattens extracted content into standard fixed-token windows.
standard = DocumentGuardrail(chunking_strategy="standard")

Both strategies use chunk_size and chunk_overlap as token counts. The selected value is returned as result.chunking_strategy and included in every chunk.metadata dictionary.

---

Project Structure

sentry-node/
├── src/sentry_node/
│   ├── application/
│   │   ├── __init__.py       # re-exports application-layer guardrails
│   │   ├── document_guardrails.py  # PDF/DOCX RAG ingestion guardrails
│   │   └── 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_document_guardrails.py
    ├── test_rbac.py
    ├── test_exceptions.py
    ├── test_config.py
    └── test_logging.py

---

License

MIT