toolclad 0.4.0__tar.gz

toolclad-0.4.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: toolclad
+Version: 0.4.0
+Summary: Reference implementation of the ToolClad declarative tool interface executor
+Author: ThirdKey AI
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

toolclad-0.4.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68.0", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toolclad"
+version = "0.4.0"
+description = "Reference implementation of the ToolClad declarative tool interface executor"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "ThirdKey AI"},
+]
+dependencies = [
+    "tomli>=1.1.0; python_version < '3.11'",
+    "click>=8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[project.scripts]
+toolclad = "toolclad.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

toolclad-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toolclad-0.4.0/tests/test_executor.py

@@ -0,0 +1,270 @@
+"""Tests for ToolClad command template interpolation and execution."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import pytest
+
+from toolclad.executor import build_command, execute, _evaluate_condition
+from toolclad.manifest import (
+    ArgDef,
+    CommandDef,
+    ConditionalDef,
+    EvidenceDef,
+    Manifest,
+    OutputDef,
+    ToolMeta,
+)
+from toolclad.validator import ValidationError
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _simple_manifest(
+    template: str = "echo {target}",
+    args: Optional[Dict[str, ArgDef]] = None,
+    mappings: Optional[Dict[str, Dict[str, str]]] = None,
+    conditionals: Optional[Dict[str, dict]] = None,
+    defaults: Optional[Dict[str, str]] = None,
+) -> Manifest:
+    """Build a minimal manifest for testing."""
+    if args is None:
+        args = {
+            "target": ArgDef(
+                name="target", position=1, required=True, type="string"
+            ),
+        }
+    cmd_conditionals = {}
+    if conditionals:
+        for k, v in conditionals.items():
+            cmd_conditionals[k] = ConditionalDef(name=k, when=v["when"], template=v["template"])
+    return Manifest(
+        tool=ToolMeta(name="test_tool", version="1.0.0", binary="echo"),
+        args=args,
+        command=CommandDef(
+            template=template,
+            mappings=mappings or {},
+            conditionals=cmd_conditionals,
+            defaults=defaults or {},
+        ),
+        output=OutputDef(format="text"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Basic interpolation
+# ---------------------------------------------------------------------------
+
+class TestBasicInterpolation:
+    def test_single_arg(self):
+        m = _simple_manifest("echo {target}")
+        result = build_command(m, {"target": "hello"})
+        assert result == "echo hello"
+
+    def test_multiple_args(self):
+        m = _simple_manifest(
+            "tool --host {host} --port {port}",
+            args={
+                "host": ArgDef(name="host", position=1, required=True, type="string"),
+                "port": ArgDef(name="port", position=2, required=True, type="port"),
+            },
+        )
+        result = build_command(m, {"host": "example.com", "port": "8080"})
+        assert result == "tool --host example.com --port 8080"
+
+    def test_default_value_used(self):
+        m = _simple_manifest(
+            "tool --rate {max_rate} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="string"),
+            },
+            defaults={"max_rate": "1000"},
+        )
+        result = build_command(m, {"target": "10.0.1.1"})
+        assert result == "tool --rate 1000 10.0.1.1"
+
+    def test_optional_arg_defaults_to_empty(self):
+        m = _simple_manifest(
+            "tool {flags} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="string"),
+                "flags": ArgDef(name="flags", position=2, required=False, type="string", default=None),
+            },
+        )
+        result = build_command(m, {"target": "10.0.1.1"})
+        assert result == "tool 10.0.1.1"
+
+
+# ---------------------------------------------------------------------------
+# Mappings
+# ---------------------------------------------------------------------------
+
+class TestMappings:
+    def test_scan_type_mapping(self):
+        m = _simple_manifest(
+            "nmap {_scan_flags} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="scope_target"),
+                "scan_type": ArgDef(
+                    name="scan_type", position=2, required=True,
+                    type="enum", allowed=["ping", "service", "syn"],
+                ),
+            },
+            mappings={
+                "scan_type": {
+                    "ping": "-sn -PE",
+                    "service": "-sT -sV --version-intensity 5",
+                    "syn": "-sS --top-ports 1000",
+                },
+            },
+        )
+        result = build_command(m, {"target": "10.0.1.0/24", "scan_type": "service"})
+        assert result == "nmap -sT -sV --version-intensity 5 10.0.1.0/24"
+
+    def test_mapping_unknown_value_empty(self):
+        """A mapping value not in the table resolves to empty string."""
+        m = _simple_manifest(
+            "tool {_mode_flags} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="string"),
+                "mode": ArgDef(
+                    name="mode", position=2, required=True,
+                    type="enum", allowed=["a", "b", "c"],
+                ),
+            },
+            mappings={"mode": {"a": "--alpha", "b": "--beta"}},
+        )
+        result = build_command(m, {"target": "x", "mode": "c"})
+        # c has no mapping, so {_mode_flags} resolves to ""
+        assert result == "tool x"
+
+
+# ---------------------------------------------------------------------------
+# Conditionals
+# ---------------------------------------------------------------------------
+
+class TestConditionals:
+    def test_conditional_included_when_true(self):
+        m = _simple_manifest(
+            "tool {_port_flag} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="string"),
+                "port": ArgDef(name="port", position=2, required=False, type="port", default="8080"),
+            },
+            conditionals={
+                "port_flag": {"when": "port != 0", "template": "-p {port}"},
+            },
+        )
+        result = build_command(m, {"target": "example.com", "port": "443"})
+        assert result == "tool -p 443 example.com"
+
+    def test_conditional_excluded_when_false(self):
+        m = _simple_manifest(
+            "tool {_port_flag} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="string"),
+                "port": ArgDef(name="port", position=2, required=False, type="port", default="0"),
+            },
+            conditionals={
+                "port_flag": {"when": "port != 0", "template": "-p {port}"},
+            },
+        )
+        # port == 0, so conditional is false -> fragment excluded
+        result = build_command(m, {"target": "example.com"})
+        assert result == "tool example.com"
+
+    def test_conditional_with_empty_string_check(self):
+        m = _simple_manifest(
+            "tool {_user_flag} {target}",
+            args={
+                "target": ArgDef(name="target", position=1, required=True, type="string"),
+                "username": ArgDef(name="username", position=2, required=False, type="string"),
+            },
+            conditionals={
+                "user_flag": {"when": "username != ''", "template": "-l {username}"},
+            },
+        )
+        # username not provided -> empty string -> conditional false
+        result = build_command(m, {"target": "10.0.1.1"})
+        assert result == "tool 10.0.1.1"
+
+        # username provided
+        result = build_command(m, {"target": "10.0.1.1", "username": "admin"})
+        assert result == "tool -l admin 10.0.1.1"
+
+    def test_compound_and_condition(self):
+        resolved = {"a": "1", "b": "2"}
+        assert _evaluate_condition("a != '' and b != ''", resolved) is True
+        assert _evaluate_condition("a != '' and b == ''", resolved) is False
+
+    def test_compound_or_condition(self):
+        resolved = {"a": "", "b": "2"}
+        assert _evaluate_condition("a != '' or b != ''", resolved) is True
+        assert _evaluate_condition("a != '' or b == 'x'", resolved) is False
+
+
+# ---------------------------------------------------------------------------
+# Validation integration
+# ---------------------------------------------------------------------------
+
+class TestValidationInBuild:
+    def test_missing_required_arg(self):
+        m = _simple_manifest("echo {target}")
+        with pytest.raises(ValidationError, match="Missing required"):
+            build_command(m, {})
+
+    def test_invalid_arg_value(self):
+        m = _simple_manifest(
+            "tool -p {port}",
+            args={
+                "port": ArgDef(name="port", position=1, required=True, type="port"),
+            },
+        )
+        with pytest.raises(ValidationError, match="out of range"):
+            build_command(m, {"port": "99999"})
+
+    def test_injection_blocked(self):
+        m = _simple_manifest("echo {target}")
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            build_command(m, {"target": "hello; rm -rf /"})
+
+
+# ---------------------------------------------------------------------------
+# Executor escape hatch
+# ---------------------------------------------------------------------------
+
+class TestExecutorEscapeHatch:
+    def test_executor_manifest_raises(self):
+        m = Manifest(
+            tool=ToolMeta(name="msf", version="1.0.0", binary="msfconsole"),
+            command=CommandDef(executor="scripts/msf-wrapper.sh"),
+        )
+        with pytest.raises(ValueError, match="custom executor"):
+            build_command(m, {})
+
+
+# ---------------------------------------------------------------------------
+# Dry-run execution
+# ---------------------------------------------------------------------------
+
+class TestDryRun:
+    def test_dry_run_returns_envelope(self):
+        m = _simple_manifest("echo {target}")
+        envelope = execute(m, {"target": "hello"}, dry_run=True)
+        assert envelope["status"] == "dry_run"
+        assert envelope["tool"] == "test_tool"
+        assert "echo hello" in envelope["command"]
+        assert envelope["duration_ms"] == 0
+
+    def test_dry_run_has_envelope_keys(self):
+        m = _simple_manifest("echo {target}")
+        envelope = execute(m, {"target": "hello"}, dry_run=True)
+        expected_keys = {
+            "status", "scan_id", "tool", "command",
+            "duration_ms", "timestamp", "output_file",
+            "output_hash", "results",
+        }
+        assert expected_keys == set(envelope.keys())

toolclad-0.4.0/tests/test_validator.py

@@ -0,0 +1,271 @@
+"""Tests for ToolClad argument type validation."""
+
+from __future__ import annotations
+
+import pytest
+
+from toolclad.manifest import ArgDef
+from toolclad.validator import ValidationError, validate_arg
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _arg(type: str, **kwargs) -> ArgDef:  # noqa: A002
+    """Create an ArgDef with the given type and optional overrides."""
+    return ArgDef(name="test", type=type, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# string
+# ---------------------------------------------------------------------------
+
+class TestStringValidation:
+    def test_valid_string(self):
+        assert validate_arg(_arg("string"), "hello") == "hello"
+
+    def test_string_with_pattern(self):
+        ad = _arg("string", pattern=r"^[a-z]+$")
+        assert validate_arg(ad, "abc") == "abc"
+
+    def test_string_pattern_mismatch(self):
+        ad = _arg("string", pattern=r"^[a-z]+$")
+        with pytest.raises(ValidationError, match="does not match pattern"):
+            validate_arg(ad, "ABC123")
+
+    def test_string_injection_rejected(self):
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            validate_arg(_arg("string"), "hello; rm -rf /")
+
+
+# ---------------------------------------------------------------------------
+# integer
+# ---------------------------------------------------------------------------
+
+class TestIntegerValidation:
+    def test_valid_integer(self):
+        assert validate_arg(_arg("integer"), "42") == "42"
+
+    def test_negative_integer(self):
+        assert validate_arg(_arg("integer"), "-5") == "-5"
+
+    def test_not_a_number(self):
+        with pytest.raises(ValidationError, match="Expected integer"):
+            validate_arg(_arg("integer"), "abc")
+
+    def test_min_max_in_range(self):
+        ad = _arg("integer", min=1, max=100)
+        assert validate_arg(ad, "50") == "50"
+
+    def test_below_min(self):
+        ad = _arg("integer", min=1, max=100)
+        with pytest.raises(ValidationError, match="below minimum"):
+            validate_arg(ad, "0")
+
+    def test_above_max(self):
+        ad = _arg("integer", min=1, max=100)
+        with pytest.raises(ValidationError, match="above maximum"):
+            validate_arg(ad, "200")
+
+    def test_clamp_below(self):
+        ad = _arg("integer", min=1, max=100, clamp=True)
+        assert validate_arg(ad, "-5") == "1"
+
+    def test_clamp_above(self):
+        ad = _arg("integer", min=1, max=100, clamp=True)
+        assert validate_arg(ad, "999") == "100"
+
+
+# ---------------------------------------------------------------------------
+# port
+# ---------------------------------------------------------------------------
+
+class TestPortValidation:
+    def test_valid_port(self):
+        assert validate_arg(_arg("port"), "443") == "443"
+
+    def test_port_zero(self):
+        assert validate_arg(_arg("port"), "0") == "0"
+
+    def test_port_max(self):
+        assert validate_arg(_arg("port"), "65535") == "65535"
+
+    def test_port_out_of_range(self):
+        with pytest.raises(ValidationError, match="out of range"):
+            validate_arg(_arg("port"), "70000")
+
+    def test_port_negative(self):
+        with pytest.raises(ValidationError, match="out of range"):
+            validate_arg(_arg("port"), "-1")
+
+    def test_port_not_a_number(self):
+        with pytest.raises(ValidationError, match="Expected port"):
+            validate_arg(_arg("port"), "http")
+
+
+# ---------------------------------------------------------------------------
+# boolean
+# ---------------------------------------------------------------------------
+
+class TestBooleanValidation:
+    def test_true(self):
+        assert validate_arg(_arg("boolean"), "true") == "true"
+
+    def test_false(self):
+        assert validate_arg(_arg("boolean"), "false") == "false"
+
+    def test_case_insensitive(self):
+        assert validate_arg(_arg("boolean"), "True") == "true"
+        assert validate_arg(_arg("boolean"), "FALSE") == "false"
+
+    def test_invalid_boolean(self):
+        with pytest.raises(ValidationError, match="Expected 'true' or 'false'"):
+            validate_arg(_arg("boolean"), "yes")
+
+
+# ---------------------------------------------------------------------------
+# enum
+# ---------------------------------------------------------------------------
+
+class TestEnumValidation:
+    def test_valid_enum(self):
+        ad = _arg("enum", allowed=["ping", "service", "syn"])
+        assert validate_arg(ad, "service") == "service"
+
+    def test_invalid_enum(self):
+        ad = _arg("enum", allowed=["ping", "service", "syn"])
+        with pytest.raises(ValidationError, match="not in allowed"):
+            validate_arg(ad, "aggressive")
+
+    def test_enum_no_allowed_list(self):
+        ad = _arg("enum")
+        with pytest.raises(ValidationError, match="requires 'allowed' list"):
+            validate_arg(ad, "anything")
+
+
+# ---------------------------------------------------------------------------
+# scope_target
+# ---------------------------------------------------------------------------
+
+class TestScopeTargetValidation:
+    def test_valid_ip(self):
+        assert validate_arg(_arg("scope_target"), "10.0.1.1") == "10.0.1.1"
+
+    def test_valid_cidr(self):
+        assert validate_arg(_arg("scope_target"), "10.0.1.0/24") == "10.0.1.0/24"
+
+    def test_valid_hostname(self):
+        assert validate_arg(_arg("scope_target"), "example.com") == "example.com"
+
+    def test_wildcard_rejected(self):
+        with pytest.raises(ValidationError, match="Wildcard"):
+            validate_arg(_arg("scope_target"), "*.example.com")
+
+    def test_injection_in_target(self):
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            validate_arg(_arg("scope_target"), "10.0.1.1; echo pwned")
+
+    def test_invalid_target(self):
+        with pytest.raises(ValidationError, match="Invalid scope target"):
+            validate_arg(_arg("scope_target"), "not a valid target at all!!!")
+
+
+# ---------------------------------------------------------------------------
+# url
+# ---------------------------------------------------------------------------
+
+class TestUrlValidation:
+    def test_valid_http_url(self):
+        ad = _arg("url")
+        assert validate_arg(ad, "https://example.com/path") == "https://example.com/path"
+
+    def test_scheme_restriction(self):
+        ad = _arg("url", schemes=["https"])
+        with pytest.raises(ValidationError, match="scheme"):
+            validate_arg(ad, "http://example.com")
+
+    def test_invalid_url(self):
+        with pytest.raises(ValidationError, match="Invalid URL"):
+            validate_arg(_arg("url"), "not-a-url")
+
+
+# ---------------------------------------------------------------------------
+# path
+# ---------------------------------------------------------------------------
+
+class TestPathValidation:
+    def test_valid_path(self):
+        assert validate_arg(_arg("path"), "/usr/share/wordlists/common.txt") == "/usr/share/wordlists/common.txt"
+
+    def test_traversal_rejected(self):
+        with pytest.raises(ValidationError, match="Path traversal"):
+            validate_arg(_arg("path"), "/etc/../../../etc/shadow")
+
+    def test_injection_in_path(self):
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            validate_arg(_arg("path"), "/tmp/$(whoami).txt")
+
+
+# ---------------------------------------------------------------------------
+# ip_address
+# ---------------------------------------------------------------------------
+
+class TestIpAddressValidation:
+    def test_valid_ipv4(self):
+        assert validate_arg(_arg("ip_address"), "192.168.1.1") == "192.168.1.1"
+
+    def test_valid_ipv6(self):
+        assert validate_arg(_arg("ip_address"), "::1") == "::1"
+
+    def test_invalid_ip(self):
+        with pytest.raises(ValidationError, match="Invalid IP address"):
+            validate_arg(_arg("ip_address"), "999.999.999.999")
+
+
+# ---------------------------------------------------------------------------
+# cidr
+# ---------------------------------------------------------------------------
+
+class TestCidrValidation:
+    def test_valid_cidr(self):
+        assert validate_arg(_arg("cidr"), "10.0.0.0/8") == "10.0.0.0/8"
+
+    def test_missing_slash(self):
+        with pytest.raises(ValidationError, match="requires '/'"):
+            validate_arg(_arg("cidr"), "10.0.0.1")
+
+    def test_invalid_cidr(self):
+        with pytest.raises(ValidationError, match="Invalid CIDR"):
+            validate_arg(_arg("cidr"), "not/a/cidr")
+
+
+# ---------------------------------------------------------------------------
+# Injection sanitization
+# ---------------------------------------------------------------------------
+
+class TestInjectionSanitization:
+    """Shell metacharacter rejection applies to string-based types."""
+
+    @pytest.mark.parametrize("char", list(";|&$`(){}[]<>!"))
+    def test_metacharacter_rejected_in_string(self, char):
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            validate_arg(_arg("string"), f"value{char}injection")
+
+    def test_semicolon_in_scope_target(self):
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            validate_arg(_arg("scope_target"), "10.0.1.1;echo")
+
+    def test_backtick_in_path(self):
+        with pytest.raises(ValidationError, match="shell metacharacters"):
+            validate_arg(_arg("path"), "/tmp/`whoami`")
+
+
+# ---------------------------------------------------------------------------
+# Unknown type
+# ---------------------------------------------------------------------------
+
+class TestUnknownType:
+    def test_unknown_type_raises(self):
+        with pytest.raises(ValidationError, match="Unknown type"):
+            validate_arg(_arg("foobar"), "anything")

toolclad-0.4.0/toolclad/__init__.py

@@ -0,0 +1,15 @@
+"""ToolClad: Declarative Tool Interface Contracts for Agentic Runtimes."""
+
+__version__ = "0.1.0"
+
+from toolclad.manifest import Manifest, load_manifest
+from toolclad.validator import validate_arg
+from toolclad.executor import build_command, execute
+
+__all__ = [
+    "Manifest",
+    "load_manifest",
+    "validate_arg",
+    "build_command",
+    "execute",
+]