CyberStrikeAI/tools

Tool Configuration Guide

Overview

Each tool has its own configuration file under the tools/ directory. This keeps tool definitions clear, easy to maintain, and manageable. The system automatically loads all .yaml and .yml files in tools/.

Configuration File Format

Each tool configuration file is a YAML file. The table below lists supported top-level fields and whether they are required. Check each item before submitting:

Field	Required	Type	Description
name	✅	string	Unique tool identifier; use lowercase letters, digits, and hyphens.
command	✅	string	Command or script to run; must be on system PATH or an absolute path.
enabled	✅	bool	Whether to register with MCP; set to false to skip the tool.
description	✅	string	Full description, multi-line Markdown, for AI and resources/read queries.
short_description	Optional	string	20–50 character summary for tool lists and lower token usage; defaults to start of description if omitted.
args	Optional	string[]	Fixed arguments prepended to the command line; often used for default scan modes.
parameters	Optional	array	Runtime parameter list; see Parameter Definition below.
arg_mapping	Optional	string	Parameter mapping mode (auto/manual/template); default auto; only set if needed.

If a field is wrong or a required field is missing, the loader skips that tool and logs a warning; other tools are unaffected.

Tool Descriptions

Short Description (short_description)

• Purpose: Used in tool lists to reduce tokens sent to the model.
• Guideline: One sentence (20–50 characters) describing the tool’s main use.
• Example: "Network scanner for discovering hosts, open ports, and services"

Detailed Description (description)

Use multi-line text and include:

1. Capabilities: What the tool does.
2. Usage scenarios: When to use it.
3. Warnings: Caveats and safety notes.
4. Examples: Optional usage examples.

Notes:

• Tool lists use short_description when present.
• If short_description is missing, the system uses the first line or first 100 characters of description.
• Full descriptions are available via MCP resources/read (URI: tool://tool_name).

This reduces token usage, especially with many tools (e.g. 100+).

Parameter Definition

Each parameter can include:

• name: Parameter name.
• type: One of string, int, bool, array.
• description: Full description (multi-line supported).
• required: Whether it is required (true/false).
• default: Default value.
• flag: CLI flag (e.g. -u, --url, -p).
• position: Zero-based index for positional arguments.
• format: One of "flag", "positional", "combined", "template".
• template: Template string when format is "template".
• options: Allowed values for enums.

Parameter Formats

• flag: Flag plus value, e.g. --flag value or -f value

  • Example: flag: "-u" → -u http://example.com

• positional: Added in order by position.

  • Example: position: 0 → first positional argument.

• combined: Single token --flag=value.

  • Example: flag: "--level", format: "combined" → --level=3

• template: Custom template.

  • Example: template: "{flag} {value}" → custom format.

Special Parameters

additional_args

Used to pass extra CLI options not defined in the parameter list. The value is split on spaces into multiple arguments.

Use cases:

• Advanced tool options.
• Options not in the schema.
• Complex argument combinations.

Example:

- name: "additional_args"
  type: "string"
  description: "Extra CLI arguments; separate multiple options with spaces"
  required: false
  format: "positional"

Usage:

• additional_args: "--script vuln -O" → ["--script", "vuln", "-O"]
• additional_args: "-T4 --max-retries 3" → ["-T4", "--max-retries", "3"]

Notes:

• Split by spaces; quoted parts are preserved.
• Ensure valid syntax to avoid command injection.
• Appended at the end of the command.

scan_type (tool-specific)

Some tools (e.g. nmap) support scan_type to override the default scan arguments.

Example (nmap):

- name: "scan_type"
  type: "string"
  description: "Scan type options; overrides default scan arguments"
  required: false
  format: "positional"

Usage:

• scan_type: "-sV -sC" → version and script scan.
• scan_type: "-A" → aggressive scan.

Notes:

• If set, it replaces the tool’s default scan arguments.
• Multiple options separated by spaces.

Parameter Description Guidelines

Parameter descriptions should include:

1. Purpose: What the parameter does.
2. Format: Expected format (e.g. URL, port range).
3. Example values: Concrete examples (list if several).
4. Notes: Permissions, performance, safety, etc.

Style:

• Use Markdown for readability.
• Use bold for important points.
• Use lists for multiple examples or options.
• Use code blocks for complex formats.

Example:

description: |
  Target IP or domain. Can be a single IP, range, CIDR, or hostname.

  **Example values:**
  - Single IP: "192.168.1.1"
  - Range: "192.168.1.1-100"
  - CIDR: "192.168.1.0/24"
  - Domain: "example.com"

  **Notes:**
  - Format must be valid.
  - Required; cannot be empty.

Parameter Types

Boolean (bool)

• true: Add only the flag (e.g. --flag).
• false: Do not add the argument.
• Accepted: true/false, 1/0, "true"/"false".

Example:

- name: "verbose"
  type: "bool"
  description: "Enable verbose output"
  required: false
  default: false
  flag: "-v"
  format: "flag"

String (string)

General-purpose; any string value.

Integer (int / integer)

For numbers (ports, levels, etc.).

Example:

- name: "level"
  type: "int"
  description: "Test level, 1-5"
  required: false
  default: 3
  flag: "--level"
  format: "combined"  # --level=3

Array (array)

Converted to a comma-separated string.

Example:

- name: "ports"
  type: "array"
  item_type: "number"
  description: "Port list"
  required: false
  # Input: [80, 443, 8080]
  # Output: "80,443,8080"

Examples

See existing configs under tools/:

• nmap.yaml: Network scanner (scan_type and additional_args).
• sqlmap.yaml: SQL injection (additional_args).
• nikto.yaml: Web server scanner.
• dirb.yaml: Directory scanner.
• exec.yaml: System command execution.

Full Example: nmap

name: "nmap"
command: "nmap"
args: ["-sT", "-sV", "-sC"]  # default scan type
enabled: true

short_description: "Network scanner for discovering hosts, open ports, and services"

description: |
  Network mapping and port scanning for hosts, services, and open ports.

  **Capabilities:**
  - Host discovery
  - Port scanning
  - Service/version detection
  - OS detection
  - NSE-based vulnerability checks

parameters:
  - name: "target"
    type: "string"
    description: "Target IP or domain"
    required: true
    position: 0
    format: "positional"

  - name: "ports"
    type: "string"
    description: "Port range, e.g. 1-1000"
    required: false
    flag: "-p"
    format: "flag"

  - name: "scan_type"
    type: "string"
    description: "Scan type options, e.g. '-sV -sC'"
    required: false
    format: "positional"

  - name: "additional_args"
    type: "string"
    description: "Extra nmap arguments, e.g. '--script vuln -O'"
    required: false
    format: "positional"

Adding a New Tool

Create a new YAML file under tools/, e.g. my_tool.yaml:

name: "my_tool"
command: "my-command"
args: ["--default-arg"]  # optional fixed args
enabled: true

# Short description (recommended) – for tool list, fewer tokens
short_description: "One-line summary of what the tool does"

# Full description – for docs and AI
description: |
  Full description; multi-line and Markdown supported.

  **Capabilities:**
  - Feature 1
  - Feature 2

  **Usage:**
  - Scenario 1
  - Scenario 2

  **Notes:**
  - Caveats
  - Permissions
  - Performance

parameters:
  - name: "target"
    type: "string"
    description: |
      Target parameter description.

      **Example values:**
      - "value1"
      - "value2"

      **Notes:**
      - Format and limits
    required: true
    position: 0
    format: "positional"

  - name: "option"
    type: "string"
    description: "Option parameter"
    required: false
    flag: "--option"
    format: "flag"

  - name: "verbose"
    type: "bool"
    description: "Verbose mode"
    required: false
    default: false
    flag: "-v"
    format: "flag"

  - name: "additional_args"
    type: "string"
    description: "Extra arguments; separate with spaces"
    required: false
    format: "positional"

Restart the service to load the new tool.

Best Practices

1. Parameter design

   • Define common parameters explicitly so the AI can use them.
   • Use additional_args for advanced cases.
   • Provide clear descriptions and examples.

2. Descriptions

   • Use short_description to reduce tokens.
   • Keep description detailed for AI and docs.
   • Use Markdown for readability.

3. Defaults

   • Set sensible defaults for common parameters.
   • Booleans often default to false.
   • Numbers according to tool behavior.

4. Validation

   • Document format and constraints.
   • Give several example values.
   • Mention limits and caveats.

5. Safety

   • Add warnings for dangerous or privileged actions.
   • Document permission requirements.
   • Remind users to use only in authorized environments.

6. Execution duration and timeout

   • If a tool often runs very long (e.g. still “running” after 10–30 minutes), treat it as abnormal and:
     • Set config.yaml → agent.tool_timeout_minutes (default 10) so long runs are stopped and resources freed.
     • Increase it (e.g. 20, 30) only when longer runs are needed; avoid 0 (no limit).
     • Use “Stop task” on the task monitor to cancel the whole run.
     • Prefer tools that support cancellation or an internal timeout so they align with the global timeout.

Disabling a Tool

Set enabled: false in the tool’s config, or remove/rename the file. Disabled tools are not listed and cannot be called by the AI.

Tool Configuration Validation

On load, the system checks:

• ✅ Required fields: name, command, enabled.
• ✅ Parameter structure and types.

Invalid configs produce startup warnings but do not prevent the server from starting. Invalid tools are skipped; others still load.

FAQ

Q: How do I pass multiple parameter values?

A: Array parameters are turned into comma-separated strings. For multiple separate arguments, use additional_args.

Q: How do I override a tool’s default arguments?

A: Some tools (e.g. nmap) support a scan_type parameter. Otherwise use additional_args.

Q: A tool has been “running” for over 30 minutes. What should I do?

A: That usually means it’s stuck. You can:

1. Set agent.tool_timeout_minutes in config.yaml (default 10) so single tool runs are stopped after that many minutes.
2. Use “Stop task” on the task monitor to stop the run immediately.
3. If the tool legitimately needs more time, increase tool_timeout_minutes (avoid setting it to 0).

Q: What if tool execution fails?

A: Check:

1. The tool is installed and on PATH.
2. The tool config is correct.
3. Parameter formats match what the tool expects.
4. Server logs for the exact error.

Q: How can I test a tool configuration?

A: Use the config test utility:

go run cmd/test-config/main.go

Q: How is parameter order controlled?

A: Use the position field for positional arguments. Position 0 (e.g. gobuster’s dir subcommand) is placed right after the command, before any flag arguments, so CLIs that expect “subcommand + options” work. Other flags are added in the order they appear in parameters, then position 1, 2, …; additional_args is appended last.

Tool Configuration Templates

Basic template

name: "tool_name"
command: "command"
enabled: true

short_description: "Short description (20–50 chars)"

description: |
  Full description: what it does, when to use it, and caveats.

parameters:
  - name: "target"
    type: "string"
    description: "Target parameter"
    required: true
    position: 0
    format: "positional"

  - name: "additional_args"
    type: "string"
    description: "Extra CLI arguments"
    required: false
    format: "positional"

Template with flag parameters

name: "tool_name"
command: "command"
enabled: true

short_description: "Short description"

description: |
  Full description.

parameters:
  - name: "target"
    type: "string"
    description: "Target"
    required: true
    flag: "-t"
    format: "flag"

  - name: "option"
    type: "bool"
    description: "Option"
    required: false
    default: false
    flag: "--option"
    format: "flag"

  - name: "level"
    type: "int"
    description: "Level"
    required: false
    default: 3
    flag: "--level"
    format: "combined"

  - name: "additional_args"
    type: "string"
    description: "Extra arguments"
    required: false
    format: "positional"

Related Documents

• Main project README: see README.md in the project root.
• Tool list: all YAML configs under tools/.
• API: see the main README for API details.