🛡️ Safety, Security & Hallucination Resistance¶

Note

👋 Hey there! Siyarix is a personal passion project built by a single developer that is growing and under active development. Some of the architectural components and features described on this page might currently be Planned, Work in Progress, or basic implementations. Stay tuned as it evolves! 🚀

Welcome to the core of Siyarix's defense mechanism! When operating an autonomous or semi-autonomous AI system, safety and security are paramount.

Info

Siyarix implements a robust, multi-layered safety architecture designed to protect your host system, secure operator data, and maintain the absolute integrity of your audit trails. Every single command passes through stages of validation, danger classification, secret redaction, and interactive review before it ever executes.

🛤️ The Safety Pipeline¶

Think of the safety pipeline as a series of rigorous checkpoints. Every tool and command must successfully pass through these stages before execution:

Note

Workflow: User input ➔ InputValidator ➔ PermissionGate ➔ DangerAnalyzer ➔ DLPEngine ➔ ShellReview ➔ AuditLogger

1. 🔍 InputValidator¶

Located in src/siyarix/security_hardening.py, the InputValidator is your first line of defense. It thoroughly validates and sanitizes any user-supplied targets to ensure they are safe before reaching the executor.

🎯 Target Validation¶

The validator automatically detects and verifies the format of your targets:

from siyarix.security_hardening import validator

# Validates IP, hostname, or URL seamlessly
valid, msg = validator.validate_target("10.0.0.1")
valid, msg = validator.validate_ip("192.168.1.0/24")
valid, msg = validator.validate_hostname("example.com")
valid, msg = validator.validate_url("https://example.com")

💉 Injection Detection¶

To prevent malicious activity, the validator actively looks for and blocks shell injection patterns:

Warning

Any command containing the following patterns will be immediately blocked to prevent shell injection attacks.

Pattern	Example	Severity
Shell pipe/redirection	`\|`, `;`, `&`, `	⛔ Blocked
Command substitution	`$(...)`	⛔ Blocked
Path traversal	`../`, `..\\`, `%2e%2e`	⛔ Blocked
Null byte	`\x00`	⛔ Blocked
Newline injection	`\r\n`	⛔ Blocked
Format string	`%x`, `%n`	⛔ Blocked
SQL injection keywords	`SELECT`, `DROP`, `UNION` + `'` or `"`	⛔ Blocked
Backtick execution	`cmd`	⛔ Blocked

🧼 Argument Sanitisation¶

If you need to clean up an argument safely, the validator can strip out dangerous characters:

safe = validator.sanitize_arg("target; rm -rf /")
# Returns: "target rm -rf " (shell metacharacters stripped)

Tip

This sanitisation removes null bytes, carriage returns, newlines, ANSI escape sequences, backticks, $(), ${}, |, ;, &, <, >, and collapses dangerous ../ path traversals.

2. ⚠️ DangerAnalyzer¶

Also found in src/siyarix/security_hardening.py, the DangerAnalyzer evaluates commands to determine how destructive they might be before they are allowed to run.

🚥 Danger Levels¶

Commands are classified into six severity levels, guiding how the system responds:

Severity	Recommendation	Example Patterns
Critical	⛔ Blocked	`sudo rm -rf /`, `mkfs`, `dd if=`, fork bombs, format drive, `chmod 777 /`, credential exfiltration
High	✋ Confirm	`shutdown`, `reboot`, `halt`, pipe curl/wget to shell, SQL DROP/DELETE without WHERE, `Remove-Item -Recurse`
Medium	⚡ Caution	`rm`, `killall`, `iptables -F`, netcat listener, crontab edit, PowerShell encoded command
Low	ℹ️ Info	`chmod`, `chown`, `crontab`
Info	📝 Note	`sudo`
Safe	✅ —	No patterns matched

🛠️ Usage¶

Using the analyzer is straightforward:

from siyarix.security_hardening import danger_analyzer

report = danger_analyzer.analyze("rm -rf /tmp")
print(report.severity)        # "medium"
print(report.is_dangerous)    # True
print(report.recommendation)  # "⚡ CAUTION — Review this command before execution."

Note

The analyzer protects both Linux and Windows environments, covering destructive patterns like registry manipulation, shadow copy deletion, event log clearing, and scheduled task abuse.

🎨 Formatted Warning¶

You can also output these warnings directly to the console with beautiful, color-coded formatting:

from rich.console import Console
danger_analyzer.format_warning(report, Console())

3. 🚧 PermissionGate¶

Located in src/siyarix/permission_gate.py, the PermissionGate acts as the bouncer for your runtime environment, providing a strict two-stage safety enforcement protocol.

⚖️ Two-Stage Check¶

Stage 1 — Syntax Check: Ensures the command is not empty and is syntactically valid.
Stage 2 — Danger Analysis: Consults the DangerAnalyzer and decides what action to take based on the severity:

Danger Severity	Gate Result	Action
`critical`	`FORBIDDEN`	Blocked with a clear reason.
`high` / `medium`	`REVIEW`	Allowed, but flagged with `requires_review=True`.
`low` / `info` / `safe`	`APPROVED`	Approved for execution.

⏱️ Rate Limiting¶

To prevent abuse or runaway scripts, the gate limits how often commands can be called:

gate = PermissionGate(rate_limit_calls=100, rate_limit_period=60.0)

Tip

By default, the limit is 100 calls per 60 seconds. The state is saved in rate_limit.json in your config directory. Exceeding this limit results in a FORBIDDEN action.

🧨 Restricted Payload Detection¶

If you pass context={"restricted_payload": True}, the gate proactively checks for highly destructive patterns (like rm -rf, mkfs, dd if=) before even applying the rate limit.

📊 Gate Stages Overview¶

The gate returns a GateResult dataclass indicating the command's status:

Stage	What it Means
`SYNTAX`	Failed basic syntax validation.
`FORBIDDEN`	Blocked either by danger analysis or rate limiting.
`PERMISSION`	Currently under permission evaluation.
`REVIEW`	Passed syntax checks, but requires manual user review.
`APPROVED`	Fully approved and ready for execution.

4. 🕵️‍♂️ DLPEngine (Data Loss Prevention)¶

Found in src/siyarix/dlp.py, the DLPEngine scans tool outputs and automatically redacts sensitive information to prevent leaks.

🔐 Redaction Patterns¶

Category	Patterns Handled
Secrets	AWS keys (`AKIA...`), GCP keys (`AIza...`), Slack tokens (`xoxb-...`), GitHub tokens (`ghp_...`), Bearer tokens, Private keys (PEM)
PII (Optional)	Email addresses, US Social Security numbers

🛠️ Usage¶

from siyarix.dlp import DLPEngine

dlp = DLPEngine(redact_secrets=True, redact_pii=False)

safe_output = dlp.redact("API key: AKIAIOSFODNN7EXAMPLE")
# Returns: "API key: [REDACTED AWS_KEY]"

safe_dict = dlp.redact_dict({"token": "ghp_xxxxxxxxxxxxxxxxxxxx"})

Note

Secrets aren't just hidden; they are clearly labeled with their category name (e.g., [REDACTED AWS_KEY]) so you know exactly what was removed.

🛡️ SecretRedactor (Comprehensive)¶

For even stricter redaction, security_hardening.py provides a SecretRedactor that covers over 20+ patterns, including AI API keys (OpenAI, Anthropic, DeepSeek, xAI, Mistral), cloud credentials, and generic password=value pairs.

from siyarix.security_hardening import redactor

safe = redactor.redact("Key: sk-ant-xxxxxxxxxxxxxxxxxxxx")
safe_env = redactor.redact_env()  # Automatically masks secrets in os.environ

5. 🧑‍💻 ShellReview¶

Located in src/siyarix/shell_review.py, the ShellReview module pauses execution to let the human operator review what the AI wants to run.

👁️ Review Prompt¶

When a command needs review, the operator sees a clean, interactive prompt:

╭──────────────── Command Execution Review ─────────────────╮
│ Tool: raw                                                 │
│ Reason: Raw shell command from LLM plan                   │
│                                                           │
│ nmap -sS -sV -O -Pn example.com                           │
╰───────────────────────────────────────────────────────────╯
Review command [edit/run/step/cancel] (run):

🕹️ Review Decisions¶

The operator has four choices:

Decision	Behavior
`run`	Execute the command exactly as shown.
`edit`	Interactively modify the command before running it.
`step`	Execute, but step through subsequent commands one by one.
`cancel`	Skip or cancel this command entirely.

Tip

CI / Non-TTY Mode: If the system detects it's running in a non-interactive environment (like a CI pipeline), it will automatically approve commands to prevent the process from hanging indefinitely.

6. 📜 AuditLogger¶

Located in src/siyarix/audit_log.py, the AuditLogger provides an solid audit trail with a tamper-evident chain of custody, ensuring absolute accountability.

🧩 The Event System¶

Every single action generates a structured AuditEvent:

@dataclass
class AuditEvent:
    event_id: str               # Unique UUID hex
    timestamp: datetime         # UTC timestamp
    event_type: str             # Category of the event
    severity: str               # info / low / medium / high / critical
    user: str                   # The user who triggered the event
    session_id: str             # Unique session identifier
    source_ip: str              # Originating IP address
    target: str                 # What resource was targeted
    action: str                 # The action performed
    result: str                 # success / failure / denied
    details: dict               # Any extra structured data
    hash_prev: str | None       # Link to the previous event's hash
    hash_current: str | None    # This event's hash

🔗 Tamper-Evident Chain¶

To guarantee that logs haven't been altered, each event's hash incorporates the hash of the previous event, creating an unbreakable chain.

Info

You can verify the integrity of your entire audit chain at any time. If someone tries to modify a past log entry, the chain will break, and the system will alert you.

audit = AuditLogger()
result = audit.verify_chain() # Returns a validation dictionary

🏷️ Event Types¶

There are 87 defined event types spanning across multiple categories, including: - Authentication: auth_login, auth_logout - Security: security_approval, dlp_violation, rate_limit_hit - System: system_start, config_change

💾 Export & CLI¶

You can easily export your logs or check status via code or CLI commands:

Command	Purpose
`/audit status`	View audit statistics and check chain integrity.
`/audit export`	Export logs to JSON or CSV formats.
`/audit verify`	Manually verify the tamper-evident chain.

Note

By default, logs are retained for 365 days. In highly sensitive "OpSec Memory-Only" mode, events are tracked in memory and never written to disk.

7. 🐳 SeccompProfile¶

Found in security_hardening.py, this module generates Docker-compatible seccomp profiles to heavily sandbox executions.

🚫 Restricted Syscalls¶

It proactively blocks over 50 dangerous system calls (like mount, ptrace, reboot, and add_key) while still allowing standard tools to function normally.

from siyarix.security_hardening import SeccompProfile

profile_path = SeccompProfile.generate_docker_seccomp()
# Returns the path to your secure JSON profile

8. ✅ Validator¶

Located in src/siyarix/validators.py, the Validator class focuses on ensuring that inputs and AI-generated plans are formatted correctly and make sense.

📐 Validated Types¶

It handles strict formatting checks for elements like: - IP Addresses (IPv4/IPv6) & CIDR blocks - RFC-compliant Hostnames & URLs - Ports, Port Ranges, and Emails

🤖 PlanStep Validation & Recovery¶

Before the AI executes a plan, the validator checks every PlanStep (e.g., verifying it has a tool, arguments, and a valid timeout).

Tip

If a command fails, plan_recovery() steps in to suggest smart, automated fixes. For example, if nmap reports all filtered ports, the recovery planner might automatically suggest adding the -Pn flag to try again.

📚 Module Quick Reference¶

Need to dive into the code? Here's where to find everything:

Module	Location	Purpose
InputValidator	`src/siyarix/security_hardening.py:88`	Validates targets and detects shell injection.
DangerAnalyzer	`src/siyarix/security_hardening.py:650`	Classifies the danger level of commands.
SecretRedactor	`src/siyarix/security_hardening.py:328`	Masks API keys, tokens, and passwords.
PermissionGate	`src/siyarix/permission_gate.py:49`	Enforces syntax checks and danger policies.
DLPEngine	`src/siyarix/dlp.py:29`	Prevents sensitive data loss in outputs.
ShellReview	`src/siyarix/shell_review.py:48`	Human-in-the-loop interactive reviews.
AuditLogger	`src/siyarix/audit_log.py:194`	Tamper-evident, personal auditing.
Validator	`src/siyarix/validators.py:598`	Format validation and AI plan recovery.
SeccompProfile	`src/siyarix/security_hardening.py:771`	Docker syscall restriction profiles.

This document serves as your guide to maintaining a secure, hallucination-resistant, and auditable Siyarix environment.