OpenJarvis/docs/api/security.md

API Reference: Security

The openjarvis.security package provides text scanning, content guardrails, file path filtering, and audit logging. All public components are documented below.

For usage examples and configuration, see the Security user guide. For the architectural design, see Security architecture.

---

Types

Core data types shared across the security subsystem.

ThreatLevel

Severity classification for individual scan findings. Ordered from least to most severe: LOW < MEDIUM < HIGH < CRITICAL.

::: openjarvis.security.types.ThreatLevel options: show_source: true show_root_heading: true heading_level: 4

RedactionMode

Controls the action taken by GuardrailsEngine when findings are detected.

::: openjarvis.security.types.RedactionMode options: show_source: true show_root_heading: true heading_level: 4

SecurityEventType

Categories of security events recorded by AuditLogger.

::: openjarvis.security.types.SecurityEventType options: show_source: true show_root_heading: true heading_level: 4

ScanFinding

A single match produced by a scanner. Includes the pattern name, matched text, position, threat level, and a human-readable description.

::: openjarvis.security.types.ScanFinding options: show_source: true show_root_heading: true heading_level: 4

ScanResult

Aggregated result from one or more scanner passes. The clean property returns True when no findings were detected; highest_threat returns the most severe ThreatLevel found.

::: openjarvis.security.types.ScanResult options: show_source: true show_root_heading: true heading_level: 4

SecurityEvent

A recorded security event, as persisted by AuditLogger.

::: openjarvis.security.types.SecurityEvent options: show_source: true show_root_heading: true heading_level: 4

---

BaseScanner

BaseScanner is the abstract base class for all scanner implementations. Implement both scan() and redact() to create a custom scanner.

::: openjarvis.security._stubs.BaseScanner options: show_source: true show_root_heading: true heading_level: 3

---

SecretScanner

Detects API keys, tokens, passwords, and credentials in text using regex patterns. See the pattern reference table in the user guide for the full list of patterns and their threat levels.

::: openjarvis.security.scanner.SecretScanner options: show_source: true show_root_heading: true heading_level: 3

---

PIIScanner

Detects personally identifiable information including email addresses, Social Security Numbers, credit card numbers, phone numbers, and public IP addresses.

::: openjarvis.security.scanner.PIIScanner options: show_source: true show_root_heading: true heading_level: 3

---

GuardrailsEngine

GuardrailsEngine wraps any InferenceEngine with security scanning on both input and output. It implements the full InferenceEngine interface, so it can be used anywhere an engine is expected.

!!! note "Registration" GuardrailsEngine is not registered in EngineRegistry. Instantiate it directly by wrapping an existing engine instance.

::: openjarvis.security.guardrails.GuardrailsEngine options: show_source: true show_root_heading: true heading_level: 3

SecurityBlockError

Raised by GuardrailsEngine when mode=RedactionMode.BLOCK and findings are detected during a scan. Catch this exception to handle blocked requests gracefully.

from openjarvis.security.guardrails import GuardrailsEngine, SecurityBlockError
from openjarvis.security.types import RedactionMode

guarded = GuardrailsEngine(engine, mode=RedactionMode.BLOCK)

try:
    response = guarded.generate(messages, model="qwen3:8b")
except SecurityBlockError as exc:
    # exc.args[0] describes the direction and finding count
    print(f"Request blocked: {exc}")

::: openjarvis.security.guardrails.SecurityBlockError options: show_source: true show_root_heading: true heading_level: 4

---

File Policy

Functions and constants for filtering sensitive file paths. Used internally by FileReadTool and the memory ingest path.

DEFAULT_SENSITIVE_PATTERNS

The default set of glob patterns used to identify sensitive files. This is a frozenset[str] exported from openjarvis.security.file_policy.

See the sensitive file patterns table in the user guide for the complete list.

::: openjarvis.security.file_policy.DEFAULT_SENSITIVE_PATTERNS options: show_source: true show_root_heading: true heading_level: 4

is_sensitive_file

::: openjarvis.security.file_policy.is_sensitive_file options: show_source: true show_root_heading: true heading_level: 4

filter_sensitive_paths

::: openjarvis.security.file_policy.filter_sensitive_paths options: show_source: true show_root_heading: true heading_level: 4

---

AuditLogger

Append-only SQLite-backed storage for security events. Subscribes to SECURITY_SCAN, SECURITY_ALERT, and SECURITY_BLOCK events on the EventBus when a bus is provided.

The default database path is ~/.openjarvis/audit.db, overridable via security.audit_log_path in config.toml.

from openjarvis.core.events import EventBus
from openjarvis.security.audit import AuditLogger
from openjarvis.security.guardrails import GuardrailsEngine
from openjarvis.security.types import RedactionMode

bus = EventBus()
audit = AuditLogger(bus=bus)

guarded = GuardrailsEngine(engine, mode=RedactionMode.WARN, bus=bus)

# Security events from guarded engine are now persisted automatically
events = audit.query(limit=10)
print(f"Logged {audit.count()} events")
audit.close()

::: openjarvis.security.audit.AuditLogger options: show_source: true show_root_heading: true heading_level: 3