Allegro
10271c6b44
Replace shell=True with list-based subprocess execution to prevent command injection via malicious user input. Changes: - tools/transcription_tools.py: Use shlex.split() + shell=False - tools/environments/docker.py: List-based commands with container ID validation Fixes CVE-level vulnerability where malicious file paths or container IDs could inject arbitrary commands. CVSS: 9.8 (Critical) Refs: V-001 in SECURITY_AUDIT_REPORT.md
42 KiB
42 KiB
Skills System Loading Flow Diagram
Overview
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SKILL LOADING FLOW │
└─────────────────────────────────────────────────────────────────────────────────┘
Phase 1: Discovery (Progressive Disclosure Tier 0-1)
┌─────────────┐ ┌─────────────────────┐ ┌─────────────────────────────┐
│ User │────▶│ skills_categories() │────▶│ Returns: │
│ Request │ │ (Tier 0) │ │ - category names │
└─────────────┘ └─────────────────────┘ │ - descriptions │
│ - skill counts │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ skills_list(category=...) │
│ (Tier 1) │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Returns: │
│ - name (≤64 chars) │
│ - description (≤1024) │
│ - category │
└─────────────────────────────┘
Phase 2: Resolution
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SKILL RESOLUTION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Search Order (First Match Wins) │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────┼──────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 1. Direct │ │ 2. Name │ │ 3. Legacy │ │
│ │ Path │ │ Match │ │ Flat MD │ │
│ ├────────────┤ ├────────────┤ ├────────────┤ │
│ │ mlops/ │ │ Search all │ │ {name}.md │ │
│ │ axolotl/ │ │ SKILL.md │ │ files │ │
│ │ SKILL.md │ │ for name │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
│ Search Directories (in order): │
│ 1. ~/.hermes/skills/ (local) │
│ 2. External dirs from config.yaml │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Phase 3: Security & Validation
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SECURITY PIPELINE │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ skill_view() │
│ Invocation │
└────────┬────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Platform │ │ Injection │ │ Path │
│ Check │ │ Scan │ │ Traversal │
├────────────┤ ├────────────┤ ├────────────┤
│ platforms: │ │ Patterns: │ │ ".." │
│ [macos] │ │ - ignore │ │ blocks │
│ │ │ prev │ │ escape │
│ Skip if │ │ - system │ │ attempts │
│ mismatch │ │ prompt │ │ │
└────────────┘ └────────────┘ └────────────┘
│ │ │
└────────────────┼────────────────┘
▼
┌─────────────────┐
│ Trust Check │
├─────────────────┤
│ Is skill from │
│ trusted dirs? │
│ (local + config)│
└─────────────────┘
Phase 4: Content Loading
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CONTENT ASSEMBLY │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────┐
│ Parse SKILL.md │
│ (Frontmatter) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Extract Metadata │
│ ├─ name │
│ ├─ description │
│ ├─ version │
│ ├─ platforms │
│ ├─ prerequisites │
│ ├─ metadata.hermes │
│ │ ├─ tags │
│ │ └─ related_... │
│ └─ setup │
└──────────┬──────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ LINKED FILES DISCOVERY │
└─────────────────────────────────────────────────────────────────────────┘
│
┌───────┼───────┐
▼ ▼ ▼
┌────────┐┌────────┐┌────────┐
│references/│templates/│ scripts/│
├────────┤├────────┤├────────┤
│ *.md ││ *.md ││ *.py │
│ docs ││ *.py ││ *.sh │
│ specs ││ *.yaml ││ helpers│
└────────┘└────────┘└────────┘
│ │ │
└───────┼───────┘
▼
┌─────────────────────┐
│ Return JSON: │
│ { │
│ name, │
│ description, │
│ content, │
│ linked_files, │
│ tags, │
│ related_skills, │
│ setup_needed, │
│ ... │
│ } │
└─────────────────────┘
Phase 5: Prerequisites & Setup
┌─────────────────────────────────────────────────────────────────────────────────┐
│ PREREQUISITES RESOLUTION │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ Required Environment Variables │
└─────────────────────────────────────────────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Check Env │ │ Gateway │ │ Local │
│ Exists? │ │ Surface │ │ CLI │
└──────┬──────┘ └─────────────┘ └─────────────┘
│ (Hint only) (Interactive
│ secret capture)
┌─────┴─────┐
▼ ▼
┌────────┐ ┌────────┐
│ Yes │ │ No │
└───┬────┘ └───┬────┘
│ │
▼ ▼
┌────────┐ ┌───────────────────────────────────────────────────────────┐
│Register│ │ Secret Capture Flow │
│for │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│passthrough│ │ │ Prompt │───▶│ User Input │───▶│ Validate │ │
└────────┘ │ │ │ User │ │ │ │ & Store │ │
│ │ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │ │
│ │ ┌────────────────────────────────────────────┘ │
│ │ ▼ │
│ │ ┌─────────────┐ ┌─────────────┐ │
│ │ │ Success │ │ Skipped │ │
│ │ │ Continue │ │ Mark setup│ │
│ │ │ │ │ as needed │ │
│ │ └─────────────┘ └─────────────┘ │
│ └───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Required Credential Files │
└─────────────────────────────────────────────────────────────────────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Exists │ │ Missing │
│ Register │ │ Mark │
│ for mount │ │ setup │
│ to remote │ │ needed │
└─────────────┘ └─────────────┘
Phase 6: Registry Integration
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TOOL REGISTRY INTEGRATION │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ tools/skills_tool.py │
└─────────────────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ skills_list │ │ skill_view │ │ skill_manage│
│ Schema │ │ Schema │ │ Schema │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ category │ │ name │ │ action │
│ (optional) │ │ file_path │ │ name │
│ │ │ (optional) │ │ content │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────┼───────────────┘
▼
┌─────────────────────────────┐
│ tools/registry.py │
│ ┌─────────────────────┐ │
│ │ registry.register() │ │
│ │ - name │ │
│ │ - toolset="skills" │ │
│ │ - schema │ │
│ │ - handler │ │
│ │ - check_fn │ │
│ │ - emoji="📚" │ │
│ └─────────────────────┘ │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Model Context │
│ (Available to LLM) │
└─────────────────────────────┘
Slash Command Flow
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SLASH COMMAND INVOCATION │
└─────────────────────────────────────────────────────────────────────────────────┘
User types: "/axolotl fine-tune llama-3"
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ agent/skill_commands.py │
│ scan_skill_commands() │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. Scan all skills directories │
│ 2. Build map: /skill-name -> skill_info │
│ 3. Match: /axolotl found │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ build_skill_invocation_message() │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Construct message: │
│ │
│ [SYSTEM: User invoked "axolotl" skill...] │
│ │
│ {SKILL.md content} │
│ │
│ [Supporting files available...] │
│ │
│ The user provided: "fine-tune llama-3" │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Add to conversation context │
│ (System or User message) │
└─────────────────────────────────────────────────────────────────────────┘
Installation Sources Flow
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SKILL INSTALLATION SOURCES │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ BUILT-IN SKILLS │
│ (Trust: builtin) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Repository Setup Command Status │
│ ───────────────────────────────────────────────────────────────────── │
│ skills/ ./setup-hermes.sh Active │
│ (bundled) → copies to ~/.hermes/skills/ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPTIONAL SKILLS │
│ (Trust: builtin) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ optional-skills/ hermes skills install <name> On-demand │
│ (bundled, inactive) → copies to ~/.hermes/skills/ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SKILLS HUB │
│ (Trust: varies by source) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ openai/ │ │ anthropic/ │ │ community/ │ │
│ │ skills │ │ skills │ │ repos │ │
│ ├───────────────┤ ├───────────────┤ ├───────────────┤ │
│ │ Trust: │ │ Trust: │ │ Trust: │ │
│ │ trusted │ │ trusted │ │ community │ │
│ │ │ │ │ │ │ │
│ │ Policy: │ │ Policy: │ │ Policy: │ │
│ │ Caution OK │ │ Caution OK │ │ Block on │ │
│ │ │ │ │ │ any finding │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │
│ Flow: │
│ 1. hermes skills search <query> │
│ 2. hermes skills install <identifier> │
│ 3. Download to quarantine │
│ 4. Security scan │
│ 5. If passed → install to ~/.hermes/skills/.hub/ │
│ 6. Record provenance in lock.json │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL DIRECTORIES │
│ (Trust: user-configured) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Config: ~/.hermes/config.yaml │
│ ───────────────────────────── │
│ skills: │
│ external_dirs: │
│ - ~/my-custom-skills │
│ - /shared/team-skills │
│ - ${WORKSPACE}/.skills │
│ │
│ Resolution: Local skills take precedence over external │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Complete End-to-End Flow
┌─────────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE SKILL LOADING SEQUENCE │
└─────────────────────────────────────────────────────────────────────────────────┘
1. USER INPUT
│
├── /command ─────────────────────────────────────────┐
│ ▼
│ ┌─────────────────────┐
│ │ Skill Commands │
│ │ Resolution │
│ └─────────────────────┘
│ │
└── skills_list() ─────────────────────────────────────┤
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Category Filter? │ │ Load Full Skill │
│ (Tier 0/1) │ │ Content │
└─────────────────────┘ └─────────────────────┘
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Return Metadata │ │ Security Pipeline │
│ (name, desc) │ │ - Platform check │
└─────────────────────┘ │ - Injection scan │
│ - Path validation │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Parse Frontmatter │
│ Extract metadata │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Resolve Prerequisites│
│ - Env vars │
│ - Credential files │
│ - Commands │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Discover Linked │
│ Files │
│ - references/ │
│ - templates/ │
│ - scripts/ │
│ - assets/ │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Assemble Response │
│ JSON with: │
│ - content │
│ - linked_files │
│ - setup status │
│ - tags, etc │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Add to Context │
│ (LLM can now use │
│ skill knowledge) │
└─────────────────────┘
Error Handling Flow
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ERROR HANDLING │
└─────────────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────┐
│ Error Type │ Response │
├───────────────────────────────────────────────────────────────────────────────┤
│ Skill not found │ Return available skills list (up to 20) │
│ Platform mismatch │ Return UNSUPPORTED readiness status │
│ Injection detected │ Log warning, load with caution │
│ Path traversal attempt │ Block with security error │
│ Setup needed (env vars) │ Return SETUP_NEEDED status + missing list │
│ File not found in skill │ Return available files organized by type │
│ Binary file requested │ Return metadata instead of content │
│ Disabled skill │ Inform user how to enable │
└───────────────────────────────────────────────────────────────────────────────┘
Diagram version: 1.0 Generated: 2024-03-30