Intent-Based Operations System¶

The Intent-Based Operations System provides a controlled, audited framework for executing infrastructure operations. Rather than running ad-hoc shell commands, operations are expressed as declarative intents that are validated, logged, and executed through a consistent interface.

Overview¶

Key Benefits: - Auditability: Every operation is logged with a hash-chained audit trail - Validation: Operations are validated against policies before execution - Reproducibility: Operations can be replayed from audit logs - Observability: Built-in metrics and failure alerting

Architecture:

Intent File (YAML)  →  run-intent.sh  →  Policy Evaluation  →  Step Execution  →  Audit Log
                                ↓
                        Dry-run preview (optional)

Quick Start¶

Running an Intent¶

# Dry-run first (always recommended for high-risk operations)
./scripts/run-intent.sh ./intents/examples/deploy-app.yaml \
  --params app=home-portal --dry-run

# Execute for real
./scripts/run-intent.sh ./intents/examples/deploy-app.yaml \
  --params app=home-portal --confirm

Viewing Execution History¶

# View metrics for the past week
./scripts/intent-metrics.sh --from 2025-12-20 --by-intent

# Verify audit log integrity
./scripts/audit-integrity-check.sh --days 7

Replaying a Past Execution¶

# Find the request ID from logs
ls logs/intents/2025-12-29/

# Replay with dry-run first
./scripts/replay-intent.sh req_1766990577_338020e6 --dry-run

# Replay for real
./scripts/replay-intent.sh req_1766990577_338020e6 --confirm

Available Intents¶

Intent	Description	Risk Level
`deploy-app`	Build, push, and deploy application	High
`restart-app`	Restart deployment pods	Medium
`scale-app`	Scale deployment replicas	Low
`observe-app`	View pod status and logs	Low
`check-logs`	Query application logs	Low
`verify-backups`	Validate backup integrity	Low
`migrate-schema`	Run database migrations	High
`create-nextjs-app`	Scaffold new Next.js application	Medium

Core Scripts¶

run-intent.sh¶

The main executor for running intents.

Usage:

./scripts/run-intent.sh <intent-file> [OPTIONS]

Options: | Option | Description | |--------|-------------| | --params key=value | Set intent parameters (repeatable) | | --dry-run | Preview without executing | | --confirm | Skip confirmation prompt |

Examples:

# Deploy home-portal with auto-versioning
./scripts/run-intent.sh ./intents/examples/deploy-app.yaml \
  --params app=home-portal version=auto --dry-run

# Restart an app with confirmation
./scripts/run-intent.sh ./intents/examples/restart-app.yaml \
  --params app=money-tracker --confirm

# Scale to 3 replicas
./scripts/run-intent.sh ./intents/examples/scale-app.yaml \
  --params app=trip-planner replicas=3 --confirm

replay-intent.sh¶

Replay a past intent execution from its audit log.

Usage:

./scripts/replay-intent.sh <request_id> [OPTIONS]

Options: | Option | Description | |--------|-------------| | --dry-run | Preview the replay without executing | | --fresh-context | Capture fresh environment context | | --override key=value | Override a parameter (repeatable) | | --confirm | Skip confirmation prompt |

Examples:

# Replay exact execution
./scripts/replay-intent.sh req_1766521519_57cf9a95

# Replay with dry-run preview
./scripts/replay-intent.sh req_1766521519_57cf9a95 --dry-run

# Replay but change the app
./scripts/replay-intent.sh req_1766521519_57cf9a95 --override app=money-tracker

intent-metrics.sh¶

Generate metrics and analytics from intent execution logs.

Usage:

./scripts/intent-metrics.sh [OPTIONS]

Options: | Option | Description | |--------|-------------| | --from DATE | Start date (YYYY-MM-DD), default: today | | --to DATE | End date (YYYY-MM-DD), default: today | | --by-intent | Show per-intent breakdown | | --format FMT | Output format: text (default), json | | --exclude-tests | Exclude test logs and incomplete executions |

Examples:

# Today's summary
./scripts/intent-metrics.sh

# Last 7 days with intent breakdown (excluding test data)
./scripts/intent-metrics.sh --from 2025-12-20 --by-intent --exclude-tests

# JSON output for dashboards
./scripts/intent-metrics.sh --format json --by-intent

Sample Output:

Intent Execution Metrics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Date range: 2025-12-19 to 2025-12-29

Summary
━━━━━━━━━━━━━━━━━━━━━━━━
  Total executions:        41
  Successful:              27
  Failed:                  14
  Success rate:            65.8%
  Avg duration:            10s

By Intent
━━━━━━━━━━━━━━━━━━━━━━━━
  Intent                  Total  Success   Failed     Rate
  ────────────────────────────────────────────────────────
  deploy-app                 16       11        5    68.7%
  observe-app                10        7        3    70.0%
  restart-app                 2        2        0   100.0%

audit-integrity-check.sh¶

Verify the integrity of hash-chained audit logs.

Usage:

./scripts/audit-integrity-check.sh [OPTIONS]

Options: | Option | Description | |--------|-------------| | --date DATE | Check specific date (YYYY-MM-DD) | | --days N | Check last N days | | --all | Check all available logs | | --format FMT | Output format: text (default), json | | --alert | Write failures to alert log |

Examples:

# Check today's logs
./scripts/audit-integrity-check.sh

# Check last week
./scripts/audit-integrity-check.sh --days 7

# Check all logs with alert on failure
./scripts/audit-integrity-check.sh --all --alert

Cron Configuration: A daily cron job is installed at /etc/cron.d/intent-audit-check that runs at 2:00 AM UTC:

0 2 * * * root /root/tower-fleet/scripts/audit-integrity-check.sh --days 1 --alert

Audit Logs¶

Every intent execution creates a hash-chained JSONL audit log at:

/root/tower-fleet/logs/intents/YYYY-MM-DD/req_<timestamp>_<hash>.jsonl

Audit Events¶

Event	Description
`intent_received`	Intent parsed and validated
`policy_evaluated`	Policy check result (approved/denied)
`execution_started`	Execution beginning
`step_started`	Individual step beginning
`step_completed`	Individual step completed
`execution_completed`	Full execution completed

Hash Chain Verification¶

Each event includes: - event_hash: SHA-256 hash of the event content - prev_hash: Hash of the previous event (forms the chain)

This creates a tamper-evident log where any modification breaks the hash chain.

Sample Audit Log¶

{"audit_version":"v1","dry_run":false,"event":"intent_received","intent":"deploy-app","params":{"app":"home-portal","version":"auto"},"prev_hash":null,"request_id":"req_1766990577_338020e6","timestamp":"2025-12-29T06:42:57Z"}
{"audit_version":"v1","decision":"approved","event":"policy_evaluated","risk_level":"high","prev_hash":"sha256:7cee51...","request_id":"req_1766990577_338020e6","timestamp":"2025-12-29T06:42:57Z"}
{"audit_version":"v1","event":"step_started","step":"build_image","command":"docker build ...","prev_hash":"sha256:c566cf...","request_id":"req_1766990577_338020e6"}
{"audit_version":"v1","event":"step_completed","step":"build_image","outcome":"success","prev_hash":"sha256:1198be...","request_id":"req_1766990577_338020e6"}
{"audit_version":"v1","event":"execution_completed","outcome":"success","prev_hash":"sha256:54d3ac...","request_id":"req_1766990577_338020e6"}

Failure Alerts¶

Failed intent executions are logged to:

/root/tower-fleet/logs/alerts/intent-failures.log

Format:

<timestamp> | <request_id> | <intent> | <outcome> | [step] | [error_message]

Example:

2025-12-29T10:15:32Z | req_1766993732_a1b2c3d4 | deploy-app | step_failed | push_image | Connection refused

Failure Types: | Outcome | Description | |---------|-------------| | policy_denied | Policy check rejected the operation | | prereqs_failed | Prerequisite commands failed | | confirmation_denied | User declined confirmation | | step_failed | An execution step failed | | verify_failed | Post-execution verification failed |

Intent File Format¶

Intent files are YAML documents that define: - Metadata (name, version, description) - Parameters with types and defaults - Policy controls - Prerequisites - Execution steps - Verification steps

Example Intent File¶

name: deploy-app
version: v1.1.0
description: Build, push, and deploy an application to Kubernetes

parameters:
  - name: app
    type: string
    required: true
    description: Application name
  - name: version
    type: string
    default: "auto"
    description: Version tag (use 'auto' for auto-increment)
  - name: registry
    type: string
    default: "10.89.97.201:30500"
    description: Docker registry URL

policy:
  risk_level: high
  controls:
    - require_clean_git: true
    - dry_run_first: true
    - confirmation: yes
    - explicit_env: true
    - lock: deploy-app-{{app}}

prerequisites:
  - name: check_docker
    command: docker info > /dev/null 2>&1

steps:
  - name: build_image
    command: |
      docker build -t {{registry}}/{{app}}:{{version}} .

  - name: push_image
    command: |
      docker push {{registry}}/{{app}}:{{version}}

  - name: update_deployment
    command: |
      kubectl set image deployment/{{app}} {{app}}={{registry}}/{{app}}:{{version}}

verify:
  - name: check_rollout
    command: kubectl rollout status deployment/{{app}} --timeout=180s

Best Practices¶

1. Always Dry-Run First¶

For high-risk operations, use --dry-run to preview what will be executed:

./scripts/run-intent.sh ./intents/examples/deploy-app.yaml \
  --params app=home-portal --dry-run

2. Use Specific Versions¶

Instead of version=auto, specify exact versions for production deployments:

./scripts/run-intent.sh ./intents/examples/deploy-app.yaml \
  --params app=home-portal version=v2.1.0 --confirm

3. Review Audit Logs¶

After operations, review the audit log for the full execution trace:

cat logs/intents/2025-12-29/req_1766990577_338020e6.jsonl | jq .

4. Monitor Metrics¶

Regularly check success rates to identify problematic intents:

./scripts/intent-metrics.sh --days 30 --by-intent

5. Verify Audit Integrity¶

Periodically verify that audit logs haven't been tampered with:

./scripts/audit-integrity-check.sh --all

Troubleshooting¶

Intent Not Found¶

Error: Intent file not found

Check that the intent file path is correct and the file exists.

Policy Denied¶

Policy evaluation: DENIED

The operation was blocked by policy. Check: - Git working directory is clean (require_clean_git) - Required dry-run was performed (dry_run_first) - Environment variables are set (explicit_env)

Step Failed¶

Step failed: build_image (exit code 1)

Check the step command output in the audit log for details:

grep "build_image" logs/intents/YYYY-MM-DD/req_*.jsonl

Hash Chain Verification Failed¶

FAIL: Hash chain broken

The audit log may have been modified. Investigate: 1. Check file modification times 2. Review system access logs 3. Restore from backup if necessary

Intent System Roadmap - Future development plans
Phase 6 Hardening Plan - Current implementation details
Production Deployment - General deployment guide

Intent-Based Operations System¶

Overview¶

Quick Start¶

Running an Intent¶

Viewing Execution History¶

Replaying a Past Execution¶

Available Intents¶

Core Scripts¶

run-intent.sh¶

replay-intent.sh¶

intent-metrics.sh¶

audit-integrity-check.sh¶

Audit Logs¶

Audit Events¶

Hash Chain Verification¶

Sample Audit Log¶

Failure Alerts¶

Intent File Format¶

Example Intent File¶

Best Practices¶

1. Always Dry-Run First¶

2. Use Specific Versions¶

3. Review Audit Logs¶

4. Monitor Metrics¶

5. Verify Audit Integrity¶

Troubleshooting¶

Intent Not Found¶

Policy Denied¶

Step Failed¶

Hash Chain Verification Failed¶

Related Documentation¶