XRisk Engine

XRisk Engine is a standalone, open-source autonomous safety and control layer for LLM and agentic systems.

It is designed to run between an agent's intended action and the action executor. XRisk evaluates risk and policy context, then returns a clear decision:

• allow
• confirm
• block

The goal is practical safety for modern AI workflows: policy governance, prompt-injection resilience, privacy controls, capability boundaries, egress restrictions, and auditability.

Why XRisk Exists

Agentic systems are useful but can fail in predictable ways:

• Over-privileged tool execution
• Prompt injection and context hijacking
• Secret and PII leakage
• Unsafe outbound network behavior
• Autonomy loops and repeated high-risk actions
• Poorly explainable safety decisions

XRisk provides composable guardrails to address these issues in one place.

Core Features

• Policy-as-code with layered precedence (global, project, user)
• Weighted risk scoring with explainable breakdown
• Prompt-injection detection and anomaly scoring
• Sensitive data detection and redaction utilities
• Capability token sandboxing (scope, TTL, single-use)
• Network egress control (allowlist and denylist)
• Circuit breaker for repeated loops and risk escalation
• Tamper-evident audit trail (hash chain)
• Approval workflow integration for confirm actions
• Model output verification (consistency and evidence checks)
• Recovery and incident summary generation
• Policy pack verification (conflicts, shadowed rules, critical allow overrides)
• Supply-chain integrity enforcement (signature and provenance gates)
• Deterministic forensics hashes and replay validation

Project Structure

xrisk-engine/
	bin/
		xrisk.js
	docs/
		openapi.yaml
	examples/
		action.json
		verify-model-input.json
		policies/
			baseline-policy-pack.json
	schemas/
		policy-pack.schema.json
		assess-result.schema.json
	src/
		adapters/
		compat/
		core/
		profiles/
		index.js
	tests/
		xrisk_engine_test.js
		security_regression_test.js
		scenario_matrix_test.js

Installation

cd xrisk-engine
npm install

Quick Start

Run all tests:

npm test

Run developer scenario matrix:

npm run test:matrix

CLI Usage

XRisk ships with a CLI entrypoint:

node bin/xrisk.js <command> [flags]

assess

Assess a proposed action and return an actionable decision payload.

node bin/xrisk.js assess --action-file examples/action.json --policies-file examples/policies/baseline-policy-pack.json --profile enterprise

You can also pipe JSON action payload via stdin:

echo '{"tool":"read_file","actorRole":"planner"}' | node bin/xrisk.js assess --profile developer

Supported flags:

• --action-file <path>
• --payload-file <path>
• --prompt <text>
• --egress-url <url>
• --profile <developer|enterprise|high_security>
• --policies-file <path>
• --compact

verify-model

Validate model output consistency and evidence requirements:

node bin/xrisk.js verify-model --input-file examples/verify-model-input.json --profile enterprise

validate-policies

Validate policy packs before rollout or CI promotion:

node bin/xrisk.js validate-policies --policies-file examples/policies/baseline-policy-pack.json

Optional strict critical-tool set:

node bin/xrisk.js validate-policies --policies-file examples/policies/baseline-policy-pack.json --critical-tools run_shell,deploy,manage_power

Programmatic Usage

import { createNodeXRisk } from './src/index.js';

const xrisk = createNodeXRisk({
	policies: {
		globalPolicies: [{ id: 'confirm-deploy', tool: 'deploy', effect: 'confirm', reason: 'approval required' }],
		projectPolicies: [{ id: 'block-power', tool: 'manage_power', effect: 'block', reason: 'blocked by default' }],
		userPolicies: []
	},
	egress: { allowedDomains: ['api.example.com'], deniedDomains: ['evil.example'] },
	telemetry: { enabled: true, localOnly: true },
	supplyChain: { requireSignatures: true, minimumProvenance: 'slsa2' }
});

const decision = xrisk.assess({
	action: { tool: 'deploy', actor: 'release-bot', actorRole: 'executor' },
	payload: { releaseId: '2026.03.10' },
	prompt: 'deploy release candidate',
	egressUrl: 'https://api.example.com/releases',
	approvalContext: { reason: 'release requested' },
	supplyChain: {
		dependencies: { release_bundle: '1.4.0' },
		artifacts: {
			signatures: { release_bundle: true },
			provenance: { release_bundle: 'slsa3' }
		}
	}
});

console.log(decision.decision);
console.log(decision.reasons);
console.log(decision.forensics);

const verifyPolicies = xrisk.validatePolicies({
	globalPolicies: [{ id: 'confirm-deploy', tool: 'deploy', effect: 'confirm' }],
	projectPolicies: [],
	userPolicies: []
});
console.log(verifyPolicies.valid);

const entries = xrisk.getAuditEntries();
const latestAssess = [...entries].reverse().find((entry) => entry.event?.type === 'assess_action');
if (latestAssess) {
	const replay = xrisk.replayDecision(latestAssess.hash);
	console.log(replay.replay);
}

How Decisions Are Made

At a high level, XRisk combines deterministic policy checks with risk signals:

1. Policy match across layered rule sets
2. Prompt-injection inspection
3. Sensitive data inspection
4. Role boundary enforcement
5. Capability token validation
6. Network egress evaluation
7. Risk score aggregation
8. Circuit breaker update
9. Audit logging and telemetry

Phase 1 additions:

10. Policy pack verification before enforcement
11. Supply-chain signature/provenance checks
12. Deterministic replay using forensic decision hashes

The output is explainable and includes rationale fields (reasons, policy match details, risk breakdown, and incident summary when blocked).

Policy Pack Schema

Use JSON policies validated by:

• schemas/policy-pack.schema.json

Example policy pack:

• examples/policies/baseline-policy-pack.json

Layer precedence is evaluated as global, then project, then user, with most restrictive matched effect winning (block > confirm > allow).

API Contract

OpenAPI contract is available at:

• docs/openapi.yaml
• docs/developer-adoption-guide.md

Response schema for decisions:

• schemas/assess-result.schema.json

Testing

Run core compatibility and engine tests:

npm run test:core

Run security regression tests:

npm run test:security

Run scenario matrix (real-world developer use cases):

npm run test:matrix

Run all suites:

npm test

CI workflow:

• .github/workflows/ci.yml

Suggested security gate commands:

npm test
node bin/xrisk.js validate-policies --policies-file examples/policies/baseline-policy-pack.json

Security Notes

• Prefer explicit policy packs for production usage.
• Keep telemetry local (localOnly: true) unless explicitly required.
• Rotate and revoke capability tokens frequently.
• Review denied/confirmed decisions in audit logs.
• Treat this project as a safety layer, not a substitute for infrastructure hardening.

Compatibility Layer

src/compat/ contains copied compatibility helpers from your existing Rex logic so migration can be incremental.

License

Apache License 2.0.

See LICENSE.

Contributing

Contributions are welcome.

Suggested workflow:

1. Fork and create a feature branch.
2. Add tests for behavior changes.
3. Run npm test before opening a PR.
4. Include rationale for policy/risk changes in the PR description.

Roadmap

• Phase 1 completed: policy verification, supply-chain integrity enforcement, deterministic replay
• Phase 2 planned: real-time threat intelligence, zero-trust workload identity, autonomous containment
• Phase 3 planned: adversarial simulation harness, multi-party cryptographic approvals, lineage/purpose controls