veto guard check

The veto guard check command validates a tool call against your policies without executing it or running an agent.

Syntax

veto guard check --tool <name> --args <json> [options]

Description

Tests a tool call against your rules to see if it would be allowed, blocked, or require approval. Useful for:

Testing policy rules before deployment
Debugging why a tool call was blocked
CI/CD validation of policy behavior
Exploring policy coverage

Required Options

Tool Name

--tool <name>

Name of the tool to check. Example:

--tool transfer_funds

Arguments

--args <json>

Tool arguments as JSON object. Example:

--args '{"amount": 600, "recipient": "user@example.com"}'

Optional Settings

Context

--context <json>

Additional context as JSON (e.g., user ID, session ID). Example:

--context '{"userId": "user_123", "role": "admin"}'

Mode

--mode <local|cloud|kernel|custom>

Validation mode:

local - Use local rules (default)
cloud - Use Veto Cloud rules
kernel - Use kernel-mode validation
custom - Use custom provider

Example:

--mode cloud

JSON Output

--json

Output result as JSON instead of human-readable text. Example:

--json

Examples

Basic Check

veto guard check \
  --tool transfer_funds \
  --args '{"amount": 600}'

Output:

Guard Check: transfer_funds

Decision: BLOCK
Rule: block-large-transfers
Reason: Amount 600 exceeds threshold of 500

Matched Rule:
  ID: block-large-transfers
  Name: Block Large Transfers
  Severity: high
  Action: block

Check with Context

veto guard check \
  --tool approve_invoice \
  --args '{"amount": 1200, "vendor": "Acme Corp"}' \
  --context '{"userId": "user_123", "role": "admin"}'

Output:

Guard Check: approve_invoice

Decision: ALLOW
Rule: admin-override
Reason: User has admin role, bypassing approval threshold

Matched Rule:
  ID: admin-override
  Name: Admin Override
  Severity: low
  Action: allow

JSON Output

veto guard check \
  --tool send_email \
  --args '{"to": "external@example.com"}' \
  --json

Output:

{
  "ok": true,
  "data": {
    "decision": "block",
    "rule": "block-external-emails",
    "ruleName": "Block External Emails",
    "reason": "Recipient domain 'example.com' is not in allowed list",
    "severity": "medium",
    "tool": "send_email",
    "arguments": {
      "to": "external@example.com"
    },
    "matchedRuleId": "block-external-emails"
  }
}

Cloud Mode

veto guard check \
  --tool deploy_app \
  --args '{"environment": "production"}' \
  --mode cloud

Output:

Guard Check: deploy_app (cloud mode)

Decision: REQUIRE_APPROVAL
Rule: require-prod-approval
Reason: Production deployments require human approval

Matched Rule:
  ID: require-prod-approval
  Name: Production Approval Gate
  Severity: critical
  Action: require_approval

Approval required from: engineering-leads

Multiple Checks (Scripted)

#!/bin/bash

tools=(
  "transfer_funds:{\"amount\":600}"
  "approve_invoice:{\"amount\":1200}"
  "send_email:{\"to\":\"test@company.com\"}"
)

for entry in "${tools[@]}"; do
  tool="${entry%%:*}"
  args="${entry#*:}"
  
  echo "Checking $tool..."
  veto guard check --tool "$tool" --args "$args" --json
  echo ""
done

Decision Types

ALLOW

Tool call is permitted.

veto guard check --tool read_file --args '{"path": "./public/data.txt"}'

Output:

Decision: ALLOW
Rule: allow-public-reads
Reason: File path is in public directory

BLOCK

Tool call is denied.

veto guard check --tool delete_file --args '{"path": "/etc/passwd"}'

Output:

Decision: BLOCK
Rule: block-system-files
Reason: Cannot delete system files

REQUIRE_APPROVAL

Tool call needs human approval.

veto guard check --tool execute_shell --args '{"command": "sudo reboot"}'

Output:

Decision: REQUIRE_APPROVAL
Rule: require-sudo-approval
Reason: Commands with sudo require approval

Testing Workflows

Test New Policy

# Generate policy
veto policy generate \
  --tool transfer_funds \
  --prompt "block transfers over $500" \
  --save ./veto/rules/financial.yaml

# Apply it
veto policy apply --file ./veto/rules/financial.yaml

# Test it
veto guard check --tool transfer_funds --args '{"amount": 400}'  # Should allow
veto guard check --tool transfer_funds --args '{"amount": 600}'  # Should block

Debug Blocked Call

# Check why call was blocked
veto guard check \
  --tool problematic_tool \
  --args '{"actual": "arguments"}' \
  --json | jq '.data.reason'

CI/CD Validation

#!/bin/bash
set -e

# Test critical paths are protected
veto guard check \
  --tool delete_database \
  --args '{}' \
  --json | jq -e '.data.decision == "block"'

veto guard check \
  --tool deploy_production \
  --args '{}' \
  --json | jq -e '.data.decision == "require_approval"'

echo "All policy tests passed"

Common Use Cases

Financial Validation

# Test transfer limits
veto guard check --tool transfer_funds --args '{"amount": 100}'   # Below limit
veto guard check --tool transfer_funds --args '{"amount": 1000}'  # Above limit
veto guard check --tool transfer_funds --args '{"amount": 10000}' # Way above

Access Control

# Test role-based access
veto guard check \
  --tool read_sensitive_data \
  --args '{}' \
  --context '{"role": "admin"}'     # Should allow

veto guard check \
  --tool read_sensitive_data \
  --args '{}' \
  --context '{"role": "viewer"}'    # Should block

Time-Based Rules

# Test deploy time restrictions (simulated)
veto guard check \
  --tool deploy_app \
  --args '{"environment": "prod"}' \
  --context '{"timestamp": "2024-03-08T16:00:00Z"}'  # Friday 4pm - should block

Troubleshooting

No Rules Matched

Guard Check: unknown_tool

Decision: ALLOW
Rule: default-allow
Reason: No matching rules found

Solution:

# Check if tool has rules
veto scan

# Generate rule for tool
veto policy generate --tool unknown_tool --prompt "..."

Invalid JSON Arguments

Error: --args is not valid JSON: Unexpected token

Solution:

# Use single quotes around JSON
veto guard check --tool name --args '{"key": "value"}'

# Or escape double quotes
veto guard check --tool name --args "{\"key\": \"value\"}"

# Or read from file
veto guard check --tool name --args "$(cat args.json)"

Cloud Connection Failed

Error: Unable to connect to Veto Cloud

Solution:

# Check authentication
veto cloud whoami

# Re-authenticate
veto cloud login

# Or use local mode
veto guard check --tool name --args '{}' --mode local

Best Practices

1. Test Edge Cases

# Test boundary values
veto guard check --tool transfer --args '{"amount": 499}'   # Just below
veto guard check --tool transfer --args '{"amount": 500}'   # Exactly at
veto guard check --tool transfer --args '{"amount": 501}'   # Just above

2. Use JSON Output for Scripting

# Parse decision programmatically
DECISION=$(veto guard check --tool xyz --args '{}' --json | jq -r '.data.decision')

if [ "$DECISION" = "allow" ]; then
  echo "Tool call would be allowed"
else
  echo "Tool call would be blocked or require approval"
fi

3. Test with Real Arguments

# Use actual tool arguments from your app
veto guard check --tool transfer_funds --args "$(cat real-transfer.json)"

4. Include Context

# Always test with realistic context
veto guard check \
  --tool sensitive_operation \
  --args '{}' \
  --context '{"userId": "user_123", "sessionId": "sess_456", "role": "admin"}'

Next Steps

Generate Policies - Create rules to test
Apply Policies - Deploy rules
Scan Coverage - Find untested tools
Launch Studio - Interactive testing

Getting Started

Commands

Documentation Index

​Syntax

​Description

​Required Options

​Tool Name

​Arguments

​Optional Settings

​Context

​Mode

​JSON Output

​Examples

​Basic Check

​Check with Context

​JSON Output

​Cloud Mode

​Multiple Checks (Scripted)

​Decision Types

​ALLOW

​BLOCK

​REQUIRE_APPROVAL

​Testing Workflows

​Test New Policy

​Debug Blocked Call

​CI/CD Validation

​Common Use Cases

​Financial Validation

​Access Control

​Time-Based Rules

​Troubleshooting

​No Rules Matched

​Invalid JSON Arguments

​Cloud Connection Failed

​Best Practices

​1. Test Edge Cases

​2. Use JSON Output for Scripting

​3. Test with Real Arguments

​4. Include Context

​Next Steps

Build docs developers (and LLMs) love

Syntax

Description

Required Options

Tool Name

Arguments

Optional Settings

Context

Mode

JSON Output

Examples

Basic Check

Check with Context

JSON Output

Cloud Mode

Multiple Checks (Scripted)

Decision Types

ALLOW

BLOCK

REQUIRE_APPROVAL

Testing Workflows

Test New Policy

Debug Blocked Call

CI/CD Validation

Common Use Cases

Financial Validation

Access Control

Time-Based Rules

Troubleshooting

No Rules Matched

Invalid JSON Arguments

Cloud Connection Failed

Best Practices

1. Test Edge Cases

2. Use JSON Output for Scripting

3. Test with Real Arguments

4. Include Context

Next Steps