skills/asif2bd_openclaw-token-optimizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6637dd34f9a2bcd2c79a9b9003cd7e76086d5fa7
asif2bd_openclaw-token-opti…/SECURITY.md

10 KiB
Raw Blame History

Security Documentation

This document provides detailed security analysis of the OpenClaw Token Optimizer skill.

Purpose

This skill helps reduce OpenClaw API costs by optimizing context loading and model selection.

Two-Part Architecture — Read This First

This skill has two distinct categories of files with different security profiles:

Category 1: Executable Scripts (scripts/*.py)

These are the actual working components of the skill.

  • Network access: None
  • External API keys: None required
  • Code execution: No eval/exec/compile
  • Data storage: Local JSON files in ~/.openclaw/workspace/memory/ only
  • Verdict: ✅ Safe to run

Category 2: Reference Documentation (references/PROVIDERS.md, assets/config-patches.json)

These are informational guides describing optional multi-provider strategies.

  • Network access: Described (not performed by these files)
  • External API keys: Referenced as examples (${OPENROUTER_API_KEY}, ${TOGETHER_API_KEY})
  • Code execution: None — these are JSON/Markdown documentation
  • Purpose: Help users who choose to configure alternative providers (OpenRouter, Together.ai, etc.)
  • Verdict: ✅ Safe files — but describe services that require external credentials if you choose to use them

Why this matters: Security scanners that flag API key patterns or external service references in documentation files are technically correct — those references exist. They are not executable, not auto-applied, and require explicit manual user action to use.

Security Flag Explanation

Why VirusTotal or AV tools may flag this skill:

  1. API key patterns in config-patches.json — ${OPENROUTER_API_KEY}, ${TOGETHER_API_KEY} are placeholder strings for optional manual configuration. They are not credentials and not automatically used.
  2. External URLs in PROVIDERS.md — References to openrouter.ai, together.ai, etc. are documentation links, not network calls.
  3. "Optimizer" keyword + file operations — Common AV heuristic false positive.
  4. Executable Python scripts with shebang — Standard Python scripts, no dangerous operations.

These are documentation-level references, not executable network code.

Shell Wrapper: optimize.sh

scripts/optimize.sh is a convenience CLI wrapper — it does nothing except call the bundled Python scripts in this same directory. It is not an installer, not a downloader, and makes no network calls.

What it does (complete source):

case "$1" in
    route|model)   python3 "$SCRIPT_DIR/model_router.py" "$@" ;;
    context)       python3 "$SCRIPT_DIR/context_optimizer.py" generate-agents ;;
    recommend)     python3 "$SCRIPT_DIR/context_optimizer.py" recommend "$2" ;;
    budget)        python3 "$SCRIPT_DIR/token_tracker.py" check ;;
    heartbeat)     cp "$SCRIPT_DIR/../assets/HEARTBEAT.template.md" ~/.openclaw/workspace/HEARTBEAT.md ;;
esac

Security properties:

  • ✅ No network requests
  • ✅ No system modifications
  • ✅ No subprocess spawning beyond the Python scripts already bundled
  • ✅ No eval, exec, or dynamic code execution
  • ✅ Only calls scripts already in this package (same directory via $SCRIPT_DIR)
  • ✅ Included in .clawhubsafe SHA256 manifest

To verify before running:

grep -E "curl|wget|nc |ncat|ssh|sudo|chmod|eval|exec\(" scripts/optimize.sh
# Should return nothing

If you prefer not to use the shell wrapper: use the Python scripts directly (all documented in SKILL.md). The wrapper is optional.

Script-by-Script Security Analysis

1. context_optimizer.py

Purpose: Analyze prompts to determine minimal context requirements

Operations:

  • Reads JSON state file from ~/.openclaw/workspace/memory/context-usage.json
  • Classifies prompt complexity (simple/medium/complex)
  • Recommends which files to load
  • Generates optimized AGENTS.md template
  • Writes usage statistics to JSON

Security:

  • ✅ No network requests
  • ✅ No code execution (no eval, exec, compile)
  • ✅ Only standard library imports: json, re, pathlib, datetime
  • ✅ Read/write permissions limited to OpenClaw workspace
  • ✅ No subprocess calls
  • ✅ No system modifications

Data Handling:

  • Stores: File access counts, last access timestamps
  • Location: ~/.openclaw/workspace/memory/context-usage.json
  • Privacy: All data local, never transmitted

2. heartbeat_optimizer.py

Purpose: Optimize heartbeat check scheduling to reduce unnecessary API calls

Operations:

  • Reads heartbeat state from ~/.openclaw/workspace/memory/heartbeat-state.json
  • Determines which checks are due based on intervals
  • Records when checks were last performed
  • Enforces quiet hours (23:00-08:00)

Security:

  • ✅ No network requests
  • ✅ No code execution
  • ✅ Only standard library imports: json, os, datetime, pathlib
  • ✅ Read/write limited to heartbeat state file
  • ✅ No system commands

Data Handling:

  • Stores: Last check timestamps, check intervals
  • Location: ~/.openclaw/workspace/memory/heartbeat-state.json
  • Privacy: All local, no telemetry

3. model_router.py

Purpose: Suggest appropriate model based on task complexity to reduce costs

Operations:

  • Analyzes prompt text
  • Classifies task complexity
  • Recommends cheapest appropriate model
  • No state file (pure analysis)

Security:

  • ✅ No network requests
  • ✅ No code execution
  • ✅ Only standard library imports: json, re
  • ✅ No file writes
  • ✅ Stateless operation

Data Handling:

  • No data storage
  • No external communication
  • Pure text analysis

4. token_tracker.py

Purpose: Monitor token usage and enforce budgets

Operations:

  • Reads budget configuration from ~/.openclaw/workspace/memory/token-budget.json
  • Tracks usage against limits
  • Provides warnings and alerts
  • Records daily/monthly usage

Security:

  • ✅ No network requests
  • ✅ No code execution
  • ✅ Only standard library imports: json, os, datetime, pathlib
  • ✅ Read/write limited to budget file
  • ✅ No system access

Data Handling:

  • Stores: Usage totals, budget limits, alert thresholds
  • Location: ~/.openclaw/workspace/memory/token-budget.json
  • Privacy: Local only, no transmission

Assets & References

Assets (Templates & Config)

  • HEARTBEAT.template.md - Markdown template for optimized heartbeat workflow
  • config-patches.json - Suggested OpenClaw config optimizations
  • cronjob-model-guide.md - Documentation for cron-based model routing

Security: Plain text/JSON files, no code execution

References (Documentation)

  • PROVIDERS.md - Multi-provider strategy documentation

Security: Plain text markdown, informational only

Verification

Check File Integrity

cd ~/.openclaw/skills/token-optimizer
sha256sum -c .clawhubsafe

Audit Code Yourself

# Search for dangerous functions (should return nothing)
grep -r "eval(\|exec(\|__import__\|compile(\|subprocess\|os.system" scripts/

# Search for network operations (should return nothing)
grep -r "urllib\|requests\|http\|socket\|download\|fetch" scripts/

# Search for system modifications (should return nothing)  
grep -r "rm -rf\|sudo\|chmod 777\|chown" .

Review Imports

All scripts use only Python standard library:

  • json - JSON parsing
  • re - Regular expressions for text analysis
  • pathlib - File path handling
  • datetime - Timestamp management
  • os - Environment variables and path operations

No third-party libraries. No network libraries.

Data Privacy

What data is stored:

  • File access patterns (which files loaded when)
  • Heartbeat check timestamps
  • Token usage totals
  • Budget configurations

Where data is stored:

  • ~/.openclaw/workspace/memory/ (local filesystem only)

What is NOT collected:

  • Prompt content
  • User messages
  • API keys
  • Personal information
  • System information
  • Network data

External communication:

  • None. Zero network requests.
  • No telemetry
  • No analytics
  • No phone home

Threat Model

What this skill CAN do:

  • Read/write JSON files in OpenClaw workspace
  • Analyze text for complexity classification
  • Generate markdown templates
  • Provide recommendations via stdout

What this skill CANNOT do:

  • Execute arbitrary code
  • Make network requests
  • Modify system files outside workspace
  • Access sensitive data
  • Run system commands
  • Spawn subprocesses

Risk Level: Minimal

  • Operates entirely within OpenClaw sandbox
  • No privileged operations
  • No external dependencies
  • Auditable source code

Provenance & Source

This skill is maintained by Asif2BD (M Asif Rahman). All source code is publicly auditable:

Every file in this skill bundle is listed in .clawhubsafe with its SHA256 checksum. Verify integrity at any time:

cd ~/.openclaw/skills/openclaw-token-optimizer
sha256sum -c .clawhubsafe

The README references the GitHub repo for users who want to review the source before installing. That link is informational — nothing in the skill auto-downloads from it.

License & Attribution

Reporting Security Issues

If you discover a security vulnerability:

  1. Do NOT open a public issue
  2. Contact: [via ClawHub or GitHub]
  3. Include: Affected files, severity, reproduction steps

Changelog

  • 2026-02-12: Added comprehensive security documentation
  • 2026-02-07: Initial release (v1.2.0)

VirusTotal Status

Current Status: False positive by heuristic analysis

Detection Reason: Generic heuristics flagging "optimizer" keyword + file operations

Actual Threat: None

Recommended Action: Whitelist this skill or review source code yourself

Bottom Line: This skill is safe. It's a productivity tool that helps reduce API costs through intelligent context loading and model selection. All code is auditable, uses only standard Python libraries, and performs no dangerous operations.

Reference in New Issue View Git Blame Copy Permalink