TOOLGUARD

pip install cognis-toolguard
toolguard scan .            # → prioritized findings in seconds

🔎 Example output

Real, reproducible output from the tool — runs offline:

$ toolguard-emit --version
toolguard 0.1.0

$ toolguard-emit --help
usage: toolguard [-h] [--version] [--format {table,json}]
                 {check,audit,policy} ...

Runtime allowlist and policy for agent tool-calls.

positional arguments:
  {check,audit,policy}
    check               evaluate a single tool-call (flags or stdin JSON)
    audit               evaluate a batch of tool-calls from a JSON array
    policy              print the active (or default) policy as JSON

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --format {table,json}
                        output format (default: table)

Blocks above are real toolguard output — reproduce them from a clone.

Sample result format (illustrative values — run on your own data for real findings):

{
"timestamp": "2023-02-16T14:30:00Z",
"actor": {
"name": "John Doe"
},
"object": {
"type": "indicator",
"guid": "1234567890abcdef",
"name": "Suspicious Domain",
"description": "Domain used by attackers",
"confidence": 0.8,
"labels": ["malware", "phishing"],
"observables": [
{
"type": "domain-name",
"value": "example.com"
},
{
"type": "ip-address",
"value": "192.168.1.100"
}
]
}
}

Usage — step by step

1. Install (Python 3.9+):

   pip install toolguard
   

2. Check a single tool-call against the policy (built-in by default). Pass the tool name and its arguments as key=value:

   toolguard check --tool shell --arg cmd="rm -rf /"
   

   Or pipe a tool-call as JSON on stdin:

   echo '{"tool":"shell","args":{"cmd":"ls"}}' | toolguard check
   

3. Use your own policy file:

   toolguard check --policy policy.json --tool http --arg url="https://example.com"
   

4. Audit a batch of tool-calls from a JSON array and read the verdicts as JSON:

   toolguard --format json audit --policy policy.json --input calls.json | jq '.[] | {tool, decision}'
   

5. Inspect / version the active policy in CI:

   toolguard policy --policy policy.json > active_policy.json
   

Contents

• Why toolguard? · Features · Quick start · Example · Architecture · AI stack · How it compares · Integrations · Install anywhere · Related · Contributing

Why toolguard?

agent safety

toolguard is single-purpose, scriptable, and self-hostable: point it at a target, get prioritized results in the format your workflow already speaks (table · JSON · SARIF), gate CI on it, and let agents drive it over MCP.

Features

• ✅ Load Policy
• ✅ Runs on Linux/macOS/Windows · Docker · devcontainer
• ✅ Ports in Python, JavaScript, Go, and Rust (ports/)

Quick start

pip install cognis-toolguard
toolguard --version
toolguard scan .                       # scan current project
toolguard scan . --format json         # machine-readable
toolguard scan . --fail-on high        # CI gate (non-zero exit)

Example

$ toolguard scan .
  [HIGH    ] TOO-001  example finding             (./src/app.py)
  [MEDIUM  ] TOO-002  another signal              (./config.yaml)

  2 findings · risk score 5 · 38ms

Architecture

flowchart LR
  IN[agent / A2A traffic] --> P[toolguard<br/>map + analyze]
  P --> OUT[graph + flags]

Use it from any AI stack

toolguard is interoperable with every popular way of using AI:

• MCP server — toolguard mcp (Claude Desktop, Cursor, Cognis.Studio, uncensored-fleet)
• OpenAI-compatible / JSON — pipe toolguard scan . --format json into any agent or LLM
• LangChain · CrewAI · AutoGen · LlamaIndex — wrap the CLI/JSON as a tool in one line
• CI / scripts — exit codes + SARIF for non-AI pipelines

How it compares

Built in the spirit of llm-guard, re-framed the Cognis way. Missing a credit? Open a PR.

Integrations

Pipes into your stack: SARIF for code-scanning, JSON for anything, an MCP server (toolguard mcp) for AI agents, and a webhook forwarder for SIEM/Slack/Jira. See docs/INTEGRATIONS.md.

Install — every way, every platform

pip install "git+https://github.com/cognis-digital/toolguard.git"    # pip (works today)
pipx install "git+https://github.com/cognis-digital/toolguard.git"   # isolated CLI
uv tool install "git+https://github.com/cognis-digital/toolguard.git" # uv
pip install cognis-toolguard                                          # PyPI (when published)
docker run --rm ghcr.io/cognis-digital/toolguard:latest --help        # Docker
brew install cognis-digital/tap/toolguard                             # Homebrew tap
curl -fsSL https://raw.githubusercontent.com/cognis-digital/toolguard/main/install.sh | sh

Related Cognis tools

• agentsmith — Config-first scaffolding and orchestration for multi-agent workflows
• skillhub — Local skill registry and installer for AI agents
• evalbench — Offline LLM / agent eval harness with regression gates
• ragkit — Batteries-included local RAG pipeline — ingest, index, serve
• memorybank — Portable long-term memory store for agents, exposed over MCP
• promptpack — Versioned prompt / template registry with A/B and rollbacks

Explore the suite → 🗂️ all 170+ tools · ⭐ awesome-cognis · 🔗 cognis-sources · 🤖 uncensored-fleet · 🧠 engram

Contributing

PRs, new rules, and demo scenarios are welcome under the collaboration-pull model — see CONTRIBUTING.md and SECURITY.md.

⭐ If toolguard saved you time, star it — it genuinely helps others find it.

Interoperability

{} composes with the 300+ tool Cognis suite — JSON in/out and a sharedOpenAI-compatible /v1 backbone. See INTEROP.md for thesuite map, composition patterns, and reference stacks.

License

Source-available under the Cognis Open Collaboration License (COCL) v1.0 — free for personal, internal-evaluation, research, and educational use; commercial / production use requires a license ([email protected]). See LICENSE.