CLI Reference

CLI Reference

This document provides comprehensive reference for the Sentrie command-line interface.

Overview

Sentrie provides a command-line interface for running policy servers and managing policy packs. The CLI is built on top of the cling framework and provides a consistent, user-friendly experience.

Global Options

All Sentrie commands support these global options:

Option	Description	Default
--help, -h	Show help information	-
--version, -v	Show version information	-
--debug	Enable debug logging	false
--log-level	Set log level (DEBUG, INFO, WARN, ERROR)	INFO

Commands

serve

Start the Sentrie HTTP server to evaluate policies.

Syntax

sentrie serve [OPTIONS]

Options

Option	Type	Default	Description
--port	int	7529	Port to listen on
--pack-location	string	./	Directory containing policy files
--listen	[]string	["local"]	Address(es) to listen on

Examples

# Start server on default port
sentrie serve

# Start server on custom port
sentrie serve --port 8080

# Start server with custom pack location
sentrie serve --pack-location /path/to/policies

# Start server on specific addresses
sentrie serve --listen 0.0.0.0 --listen 127.0.0.1

# Start server with debug logging
sentrie serve --debug --log-level DEBUG

Environment Variables

The serve command respects these environment variables:

Variable	Description	Default
SENTRIE_DEBUG	Enable debug logging	false
SENTRIE_LOG_LEVEL	Log level	INFO
SENTRIE_PORT	Default port	7529

Server Behavior

When you start the server, it will:

1. Load the policy pack from the specified location
2. Parse and validate all .sentrie files
3. Create an index of policies and rules
4. Start the HTTP server on the specified port
5. Log startup information and any errors

Pack Loading

The server looks for policy files in the specified directory:

• Policy files: *.sentrie - Sentrie policy files
• Pack file: sentrie.pack.toml - Pack metadata (optional)
• JavaScript modules: *.js - JavaScript modules for use statements

Error Handling

If the server encounters errors during startup:

• Policy parsing errors: Server will not start, errors are logged
• Pack loading errors: Server will not start, errors are logged
• Port binding errors: Server will not start, error is logged
• Runtime errors: Server continues running, errors are logged

Graceful Shutdown

The server supports graceful shutdown:

• SIGINT (Ctrl+C): Graceful shutdown
• SIGTERM: Graceful shutdown
• SIGKILL: Immediate shutdown

HTTP API

When the server is running, it provides a REST API for policy evaluation.

Base URL

http://localhost:7529

Endpoints

Decision Execution

POST /decision/{namespace}/{policy}/{rule}?{runconfig_params}

Execute a specific rule with the provided facts.

Path Parameters

• namespace: The namespace containing the policy (can contain multiple segments separated by ’/’)
• policy: The policy name (second to last segment in the path)
• rule: The rule name to execute (last segment in the path)

Path Structure

The path follows this pattern: /decision/{namespace}/{policy}/{rule} where:

• The last segment is the rule name
• The second to last segment is the policy name
• Everything before that is the namespace (can contain multiple /-separated segments)

Examples

• /decision/sh/sentra/auth/v1/user/allow → namespace: sh/sentra/auth/v1, policy: user, rule: allow
• /decision/org/department/team/policy/rule → namespace: org/department/team, policy: policy, rule: rule

Query Parameters

• runconfig_params: Optional configuration parameters for rule execution

Request Body

The request body should be a JSON object containing the facts to evaluate:

{
  "user": {
    "id": "user123",
    "role": "admin"
  },
  "resource": {
    "id": "resource456",
    "owner": "user123"
  }
}

Response

The response is a JSON object containing the decision and any attachments:

{
  "decision": true,
  "attachments": {
    "reason": "User is admin",
    "timestamp": "2025-01-27T10:00:00Z"
  }
}

Error Responses

400 Bad Request

{
  "error": "Invalid request body",
  "message": "Expected JSON object"
}

404 Not Found

{
  "error": "Policy not found",
  "message": "Policy 'com/example/auth/user' not found"
}

500 Internal Server Error

{
  "error": "Policy evaluation failed",
  "message": "Error in rule 'allow': division by zero"
}

Example Requests

Simple Authorization

curl -X POST "http://localhost:7529/decision/com/example/auth/user/allow" \
  -H "Content-Type: application/json" \
  -d '{"user": {"id": "user123", "role": "admin"}}'

Resource Access Control

curl -X POST "http://localhost:7529/decision/com/example/resources/document/canRead" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {"id": "user123", "role": "user"},
    "document": {"id": "doc456", "owner": "user123"}
  }'

Complex Policy with Attachments

curl -X POST "http://localhost:7529/decision/com/example/billing/pricing/calculatePrice" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {"id": "user123", "isPremium": true},
    "product": {"id": "prod789", "price": 100.0}
  }'

Configuration

Pack Configuration

Create a sentrie.pack.toml file in your pack directory:

schema_version = "0.1.0"
name = "my-policy-pack"
version = "1.0.0"
description = "My policy pack"
license = "MIT"
repository = "https://github.com/myorg/my-policy-pack"

[engines]
sentrie = "0.1.0"

[authors]
"John Doe" = "john@example.com"

[permissions]
fs_read = ["/etc/passwd"]
net = ["http://example.com"]

[metadata]
"custom" = "value"

Environment Configuration

Set environment variables for configuration:

export SENTRIE_DEBUG=true
export SENTRIE_LOG_LEVEL=DEBUG
export SENTRIE_PORT=8080
sentrie serve

Logging Configuration

Configure logging levels and output:

# Debug logging
sentrie serve --debug

# Custom log level
sentrie serve --log-level WARN

# Environment variable
export SENTRIE_LOG_LEVEL=ERROR
sentrie serve

Troubleshooting

Common Issues

Port Already in Use

# Error: port 7529 is already in use
# Solution: Use a different port
sentrie serve --port 8080

Policy Not Found

# Error: Policy 'com/example/auth/user' not found
# Solution: Check namespace and policy names
# Make sure the policy file exists and is valid

Invalid Policy Syntax

# Error: Policy parsing failed
# Solution: Check the policy file syntax
# Use --debug for detailed error messages

Pack Loading Failed

# Error: Pack loading failed
# Solution: Check the pack directory exists
# Verify sentrie.pack.toml is valid

Debug Mode

Enable debug mode for detailed logging:

sentrie serve --debug --log-level DEBUG

This will show:

• Policy loading progress
• Detailed error messages
• Request/response logging
• Performance metrics

Performance Tuning

Memory Usage

The server uses memory for:

• Policy index
• JavaScript VM pools
• Call memoization cache
• Module bindings

Monitor memory usage and adjust cache sizes if needed.

Concurrent Requests

The server handles concurrent requests efficiently:

• Each request gets its own execution context
• JavaScript VMs are pooled for reuse
• Policy evaluation is stateless

Examples

Complete Example

1. Create a policy pack:

mkdir my-policy-pack
cd my-policy-pack

2. Create a policy file:

auth.sentrie

namespace com/example/auth

policy user {
  rule allow = default false when user.role == "admin" {
    yield true
  }

  export decision of allow
}

3. Create a pack file:

sentrie.pack.toml

schema_version = "0.1.0"
name = "my-policy-pack"
version = "1.0.0"
description = "My policy pack"

[engines]
sentrie = "0.1.0"

4. Start the server:

sentrie serve --pack-location . --port 8080

5. Test the policy:

curl -X POST "http://localhost:8080/decision/com/example/auth/user/allow" \
  -H "Content-Type: application/json" \
  -d '{"user": {"role": "admin"}}'

Production Deployment

For production deployment:

1. Use a reverse proxy (nginx, Apache)
2. Enable HTTPS with SSL certificates
3. Set up monitoring and logging
4. Configure load balancing for high availability
5. Use environment variables for configuration
6. Set up health checks for the API

Docker Deployment

FROM golang:1.25-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o sentrie .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/sentrie .
COPY --from=builder /app/policies ./policies
EXPOSE 7529
CMD ["./sentrie", "serve", "--pack-location", "./policies"]

Best Practices

1. Use Descriptive Names

# Good
sentrie serve --pack-location ./production-policies

# Bad
sentrie serve --pack-location ./p

2. Organize Policies

policies/
├── auth/
│   ├── user.sentrie
│   └── admin.sentrie
├── billing/
│   └── pricing.sentrie
└── sentrie.pack.toml

3. Use Environment Variables

production.sh

export SENTRIE_LOG_LEVEL=WARN
export SENTRIE_PORT=8080
sentrie serve --pack-location ./policies

4. Monitor Performance

# Enable debug logging to monitor performance
sentrie serve --debug --log-level DEBUG

5. Handle Errors Gracefully

# Check exit codes
if ! sentrie serve; then
  echo "Failed to start server"
  exit 1
fi