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
485 lines
42 KiB
Markdown
485 lines
42 KiB
Markdown
# 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*
|