claw-guard 0.1.1

Security and policy engine for ClawDB
Documentation

claw-guard

Policy-driven security, session management, and audit enforcement for ClawDB workloads.

claw-guard is a Rust crate and service that evaluates authorization decisions at runtime using role and scope context, task/resource metadata, and configurable risk scoring. It supports allow, deny, and mask outcomes, with durable audit logging and a gRPC interface for external integration.

What This Crate Provides

  • Policy engine with TOML-defined rules (allow, deny, mask)
  • Session creation, validation, revocation, and pagination
  • Risk-aware access decisions based on action/resource/time-of-day heuristics
  • Mask directives for field-level data handling
  • Structured audit log writer/reader on SQLite
  • gRPC server exposing decisioning and admin APIs

Install

Add to Cargo.toml:

[dependencies]
claw-guard = "0.1.1"

Architecture Overview

  • Guard: top-level coordinator for policy engine, session manager, and audit components
  • PolicyEngine: loads and evaluates policy files from a directory
  • SessionManager: issues JWT-backed sessions and validates/revokes them
  • AuditWriter/AuditReader: records and queries access events
  • gRPC service: wraps the same Guard flows over a network API

Configuration

Configuration is loaded from environment variables using GuardConfig::from_env().

Required:

  • CLAW_GUARD_JWT_SECRET: signing key for HS256 session tokens

Optional:

  • CLAW_GUARD_DB_PATH (default: claw_guard.db)
  • CLAW_GUARD_POLICY_DIR (default: policies)
  • CLAW_GUARD_TLS_CERT_PATH (default: certs/server.crt)
  • CLAW_GUARD_TLS_KEY_PATH (default: certs/server.key)
  • CLAW_GUARD_SENSITIVE_RESOURCES (comma-separated)
  • CLAW_GUARD_AUDIT_FLUSH_INTERVAL_MS (default: 100)
  • CLAW_GUARD_AUDIT_BATCH_SIZE (default: 500)
  • CLAW_GUARD_RISK_THRESHOLDS_WRITE_WEIGHT (default: 0.25)
  • CLAW_GUARD_RISK_THRESHOLDS_DELETE_WEIGHT (default: 0.4)
  • CLAW_GUARD_RISK_THRESHOLDS_SENSITIVE_WEIGHT (default: 0.35)
  • CLAW_GUARD_RISK_THRESHOLDS_OFF_HOURS_WEIGHT (default: 0.2)
  • CLAW_GUARD_RISK_THRESHOLDS_DENY_THRESHOLD (default: 0.9)

Quick Start (Library)

use claw_guard::{AccessResult, Guard, GuardConfig, ZeroizeString};
use std::path::PathBuf;
use uuid::Uuid;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
	let config = GuardConfig {
		db_path: "claw_guard.db".to_string(),
		jwt_secret: ZeroizeString::new("replace-me"),
		policy_dir: PathBuf::from("./policies"),
		tls_cert_path: PathBuf::from("./certs/server.crt"),
		tls_key_path: PathBuf::from("./certs/server.key"),
		risk_thresholds: Default::default(),
		sensitive_resources: vec!["finance_records".to_string()],
		audit_flush_interval_ms: 100,
		audit_batch_size: 500,
	};

	let guard = Guard::new(config).await?;

	let session = guard
		.session_manager
		.create_session(Uuid::new_v4(), "analyst", vec!["tool:*".into()], 3600)
		.await?;

	match guard
		.check_access_with_task(&session.token, "read", "customer_records", "reporting")
		.await?
	{
		AccessResult::Allowed => println!("allowed"),
		AccessResult::Denied { reason } => println!("denied: {reason}"),
		AccessResult::Masked { fields } => println!("masked fields: {}", fields.len()),
	}

	Ok(())
}

Policy Format (TOML)

Example policy file:

name = "base"
description = "baseline guard policy"
priority = 100

[[rules]]
type = "allow_if"
condition = { role_in = ["analyst"], resource_is = "docs" }

[[rules]]
type = "deny_if"
condition = { task_matches = "scheduling", resource_is = "finance_records" }
reason = "finance blocked during scheduling"

[[rules]]
type = "mask_field"
field_pattern = "$.ssn"
mask_type = "redact"

gRPC Server

The crate ships with a binary:

cargo run --bin guard-server

Service methods (see proto/guard.proto):

  • CheckAccess
  • CreateSession
  • ValidateSession
  • RevokeSession
  • AddPolicy
  • ListPolicies
  • RemovePolicy
  • QueryAuditLog

TLS cert and key paths are read from GuardConfig.

Data Model and Persistence

  • Uses SQLite via sqlx
  • Applies migrations from migrations/
  • Stores sessions, roles, policies, and audit events
  • Persists policy metadata while allowing filesystem policy loading and reload

Local Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

For benchmark runs:

cargo bench

Versioning

Current version: 0.1.1

License

MIT. See LICENSE.