teos-sentinel-shield

v5.2.9

Published

2 days ago

Sovereign Execution Control & Compliance Engine - Pre-execution security for AI, Solana, and banking compliance

0High
0Medium
0Low

ai-security runtime-enforcement deterministic-engine execution-governance audit-compliance sentinel-shield solana cbe sama

TEOS Sentinel Shield - v5.2.6 (Engine v5.0.0 GA baseline)

Deterministic AI runtime security middleware that sits between AI-generated actions and execution — providing inspection, risk scoring, policy enforcement, blocking, auditability, and compliance visibility before commands, code, scripts, and agent actions are executed.

Production API: https://teos-sentinel-shield-production.up.railway.app (optional — local mode needs no API)

Engine: v5.0.0 Rules: 258 Persistence: Redis Rate limiting: Redis-backed tiered rate limiting Authentication: x-api-key

Version Architecture

Core engine: v5.0.0 GA (258 rules, hosted scan API)
GitHub Action: v5.2.4 (zero-dependency node24; local + remote modes)

Zero-Exfiltration Local Mode

For teams with strict compliance requirements or sensitive codebases, TEOS Sentinel Shield can run 100% locally. The rule engine is bundled into the Action (compiled with ncc), so it evaluates the scan-target in-process on your runner:

No external API calls
No commands or code leave your environment
No hosting dependency and no API key required

- name: Gate step with TEOS Sentinel Shield (local)
  uses: Elmahrosa/[email protected]
  with:
    mode: local
    engine: core   # core | ci | deps | banking | solana | evm | tokenIntel | dueDiligence
    scan-target: 'npm run build'

| mode | Behaviour | | --- | --- | | auto (default) | local when no api-key is supplied; remote when one is. | | local | Runs the bundled engine inside the runner — no network calls. | | remote | Calls the hosted scan API (audit history, dashboards, tiered rules). |

Local mode uses the bundled rule set. For audit logging, dashboard access and continuous rule updates, use mode: remote with your TEOS API key.

What This Is

TEOS Sentinel Shield is execution-control infrastructure for autonomous AI systems.

It is designed to inspect an action before execution and produce a deterministic security decision.

Infrastructure middleware — not merely a dashboard or landing page
Deterministic rule engine — reproducible policy decisions
Runtime enforcement layer — pre-execution security control for AI agents and automated systems
Audit-first architecture — security decisions are recorded for inspection and compliance
Multi-engine security analysis — multiple specialized detection engines operate within the v5 security pipeline
API-first — designed to integrate with autonomous agents, CI/CD systems, MCP workflows, and other execution environments

Core flow

INPUT
  ↓
Security Analysis
  ↓
258 Deterministic Rules
  ↓
Risk / Policy Evaluation
  ↓
ALLOW / WARN / REVIEW / BLOCK
  ↓
Audit + Persistence

Production Status

The verified production release baseline is:

Version:       v5.0.0
Engine:        v5.0.0
Rules:         258
Environment:   production
Store:         Redis
Authentication: x-api-key
Rate limiting: Redis-backed tiered
Audit store:   Redis fallback
PostgreSQL:    Not configured
Release:       976235e28562610f917d8eb51d56ab054b838795

Production health reports the engine as online and identifies the deployed release with commit:

976235e28562610f917d8eb51d56ab054b838795

Who It's For

TEOS Sentinel Shield is designed for systems that allow AI or automation to generate actions that may affect real infrastructure.

Typical integration targets include:

Autonomous AI agent platforms
MCP-based agent workflows
CI/CD security gates
DevSecOps automation
Cloud operations
Code-generation pipelines
Shell and command execution systems
Enterprise autonomous systems
Sovereign AI environments
Security research and validation environments

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     TEOS SENTINEL SHIELD                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   AI / Agent / MCP / CI / Automation Input                 │
│                         │                                   │
│                         ▼                                   │
│              ┌──────────────────────┐                       │
│              │ Security Inspection  │                       │
│              └──────────┬───────────┘                       │
│                         │                                   │
│                         ▼                                   │
│              ┌──────────────────────┐                       │
│              │  Multi-Engine Scan   │                       │
│              │   258 Security Rules │                       │
│              └──────────┬───────────┘                       │
│                         │                                   │
│                         ▼                                   │
│              ┌──────────────────────┐                       │
│              │ Policy / Risk Engine │                       │
│              └──────────┬───────────┘                       │
│                         │                                   │
│             ┌───────────┼────────────┐                      │
│             ▼           ▼            ▼                      │
│          ALLOW        WARN        REVIEW / BLOCK             │
│             │           │            │                      │
│             └───────────┼────────────┘                      │
│                         ▼                                   │
│              ┌──────────────────────┐                       │
│              │ Redis Audit / State  │                       │
│              └──────────┬───────────┘                       │
│                         │                                   │
│                         ▼                                   │
│                  API / Integration                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Security Engines

The v5 engine uses multiple specialized analysis engines rather than relying on a single pattern set.

The production release contains:

258 total security rules
8 security analysis engines

| Engine | Rules | Focus | | --- | --- | --- | | core (default) | 95 | Execution, shell, and code-execution risk | | banking | 32 | Banking and financial-transaction compliance | | solana | 29 | Solana program and on-chain risk | | evm | 21 | EVM smart-contract risk | | ci | 23 | CI/CD pipeline risk | | tokenIntel | 25 | Token intelligence | | dueDiligence | 25 | Due-diligence review | | deps (dependency) | 8 | Dependency and CVE risk | | Total | 258 | |

The GitHub Action selects any pack locally with the engine: input — all packs run in-process on the runner, with no network call and no API key. The hosted POST /scan endpoint evaluates with the core pack; call GET /engines to list the available engines, their credit cost, and their current rule counts.

The engines are designed to identify different classes of execution and application security risk.

The authoritative rule catalog in the repository is the source of truth for the exact current rule definitions.

Do not treat historical rule counts from earlier releases as current v5 production counts.

Verdict Model

TEOS Sentinel Shield uses explicit security verdicts rather than probabilistic model output.

ALLOW
WARN
REVIEW
BLOCK

The exact verdict is determined by the configured v5 policy and security engines.

A verdict is accompanied by security analysis information that can include:

rule identification
severity
risk information
detection reason
input classification
engine information
timestamp
audit information

The system is designed so that security decisions can be inspected and reproduced from the same input and rule configuration.

Production API

Health

GET /health

Production endpoint:

https://teos-sentinel-shield-production.up.railway.app/health

The health response exposes production engine information including:

service status
engine version
rule count
environment
release/deployment identifier
authentication mode
rate-limiting mode
audit-store status
dependency health

Scan

The scan API evaluates an input before execution.

POST /scan

Authentication is controlled through the configured API-key mechanism.

Example:

curl -X POST \
  https://teos-sentinel-shield-production.up.railway.app/scan \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"command":"rm -rf /"}'

A scan response contains the security decision and associated analysis metadata.

Authentication

Production API authentication uses:

x-api-key

Private credentials must remain outside client-side bundles and must be supplied through secure server-side configuration.

Sentinel Shield is not designed to expose provider credentials or private API keys to browsers.

Rate Limiting

Production rate limiting is:

Redis-backed tiered rate limiting

Redis provides the shared state required for production request controls.

This prevents rate-limit state from depending solely on process-local memory.

Audit and Persistence

The production release uses Redis for persistent runtime state and audit-related storage.

Production health currently reports:

Store: Redis
Audit store: Redis fallback
PostgreSQL: Not configured

The architecture is therefore not dependent on a local JSON event file as its production persistence mechanism.

Production Deployment

The verified production deployment runs on Railway.

Production service:

teos-sentinel-shield-production.up.railway.app

The production deployment is tied to the verified release commit:

976235e28562610f917d8eb51d56ab054b838795

Production environment

The production service reports:

env: production
engine: v5.0.0
rules: 258
store: redis
auth: x-api-key
rateLimiting: redis-backed-tiered

Local Development

Local development should use the repository's configured development scripts and environment configuration.

Production credentials must never be committed to the repository.

Local development configuration must not be confused with the production deployment configuration.

Security Principles

Deterministic Enforcement

Security decisions are produced through explicit rules and policy logic rather than relying on probabilistic LLM output.

Pre-Execution Control

Sentinel Shield is intended to evaluate an action before it reaches the execution layer.

Defense in Depth

Multiple security engines and rule classes provide layered inspection rather than relying on one detection mechanism.

Auditability

Security decisions are designed to produce structured information suitable for audit and compliance workflows.

Server-Side Secret Handling

Private API credentials and security-sensitive configuration remain server-side.

Production State

Production state is backed by Redis rather than relying on a developer's local filesystem.

Explicit Verdicts

The engine communicates an explicit security outcome:

ALLOW
WARN
REVIEW
BLOCK

Repository Structure

The repository contains the Sentinel Shield application, security engines, configuration, tests, documentation, and deployment assets.

The exact current production rule catalog and implementation are authoritative over historical README examples.

For the current release, use the repository's machine-readable rule catalog and automated test suite as the source of truth.

Release Baseline

The frozen v5.0.0 production baseline is:

Commit:
976235e28562610f917d8eb51d56ab054b838795

Version:
5.0.0

Engine:
v5.0.0

Rules:
258

ioredis:
5.11.1

This release is the verified production baseline for TEOS Sentinel Shield.

Compliance and Governance

TEOS Sentinel Shield is designed as security and execution-control infrastructure for environments where autonomous systems require explicit governance controls.

The system provides technical enforcement mechanisms including:

pre-execution inspection
deterministic rule evaluation
explicit verdicts
authentication
authorization boundaries
rate limiting
audit persistence
security telemetry
versioned engine metadata

Compliance claims must be evaluated against the actual deployment configuration, applicable jurisdiction, and governing institutional requirements.

Technical enforcement should not be interpreted as a claim of automatic regulatory certification.

GitHub Action

TEOS Sentinel Shield ships as a zero-dependency JavaScript GitHub Action (node24) so CI/CD pipelines can gate any step on a deterministic verdict before it executes.

# Local mode — runs inside the runner, no API key, no network
- name: Gate step with TEOS Sentinel Shield (local)
  uses: Elmahrosa/[email protected]
  with:
    mode: local
    scan-target: 'npm run build'

# Remote mode — calls the hosted API (production: pin the full commit SHA instead)
- name: Gate step with TEOS Sentinel Shield (remote)
  uses: Elmahrosa/[email protected]
  with:
    mode: remote
    api-key: ${{ secrets.TEOS_API_KEY }}
    scan-target: 'npm run build'

The run fails (exit 1) whenever the engine returns a BLOCK verdict, or — in remote mode — when the scan API is unreachable (fail-closed by default). The step after it never executes.

Inputs

| Input | Required | Default | Description | | --- | --- | --- | --- | | mode | no | auto | auto, local (in-runner, no network), or remote (hosted API). | | api-key | remote only | — | x-api-key for the TEOS Sentinel Shield API. Not needed in local mode. | | scan-target | yes | . | Command, code file, script, or directory to inspect. | | engine | no | core | Rule pack in local mode: core, ci, deps, banking, solana, evm, tokenIntel, dueDiligence. | | api-url | no | https://teos-sentinel-shield-production.up.railway.app | Base URL of the scan API (remote mode). | | api-path | no | /scan | Endpoint path that accepts the scan payload (POST). | | fail-open | no | false | true = pass when the API is unreachable (not recommended). |

Outputs

| Output | Description | | --- | --- | | verdict | ALLOW, WARN, REVIEW, or BLOCK. | | risk-score | Risk score (0–100) from the engine. | | rule-id | Highest-severity rule that matched. |

Verdict behavior

| Verdict | Action run | | --- | --- | | ALLOW | Pass. | | WARN | Pass, with a warning annotation. | | REVIEW | Pass, with a notice annotation. | | BLOCK | Fail (exit 1) — downstream steps are skipped. | | ERROR / unknown / API unreachable | Fail closed (exit 1) unless fail-open: 'true'. |

Recommended workflow setup

permissions: {}            # the action needs no token permissions

jobs:
  guard:
    runs-on: ubuntu-latest
    steps:
      # Production: pin the full commit SHA and omit `api-url`.
      - uses: Elmahrosa/teos-sentinel-shield@<full-commit-sha>
        with:
          api-key: ${{ secrets.TEOS_API_KEY }}
          scan-target: 'npm run build'

| Input | Default | Description | | ----------------- | ------- | -------------------------------------------------------------- | | timeout-seconds | 15 | Per-request timeout, clamped to 10–60. |

What is sent to the API

Remote mode only. In local mode nothing is sent anywhere — the engine runs in-process inside the runner. In remote mode, the action sends only the scan-target string plus GitHub context (repository, sha, ref, workflow, actor, runnerOs) to the scan API. It does not read or upload file contents. Because scan-target leaves the runner:

Never interpolate secrets into it. As a best-effort safety net, the action refuses to send a target that matches known credential formats (GitHub, AWS, Slack, Google, GitLab, npm, Stripe, sk- keys, JWTs, Bearer credentials, private-key blocks), the api-key itself, or a high-entropy string, and fails the step instead. It is a denylist: it does not catch every secret (for example plain hex keys or short passwords). Treat it as a last line of defence, not a guarantee.
Untrusted text (scan-target, API response fields) is sanitised before it reaches logs, annotations, step summaries or step outputs. ruleId must be a plain identifier and score is clamped to 0-100; a response that breaks the contract is reported as ERROR and fails the step.
api-url must be https and either the default endpoint or an origin listed in the TEOS_APPROVED_API_URLS environment variable (comma-separated; set it at org level).

Availability behaviour

Network errors and HTTP 502/503/504 are retried once, then fail closed. fail-open: 'true' passes without a verdict, emits a ::error:: annotation, sets verdict=UNVERIFIED, and is ignored on protected branches. Do not use it in release workflows.

Building

npm run build:action   # ncc bundles src/action.js -> dist/index.js

The compiled dist/index.js is committed so the action runs natively on the GitHub Actions runner with no dependency install at execution time.

License

TEOS Egypt Sovereign License (TESL)

TEOS Sentinel Shield is governed by the TEOS Egypt Sovereign License (TESL) and associated constitutional governance framework.

It is not released under MIT or Apache licensing.

See the repository's authoritative LICENSE file for the exact terms. This repository is source-available, not open source.

Product Position

TEOS Sentinel Shield

Execution Firewall for Autonomous AI Agents

Built by Elmahrosa International.

Law Over Code.

Inspect.
Decide.
Enforce.
Audit.