agent-security-lens 0.1.0

package/examples/dot-openclaw/.openclaw/openclaw.json

@@ -0,0 +1,17 @@
+{
+  "mcp": {
+    "servers": {
+      "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
+      }
+    }
+  },
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "botToken": "${DISCORD_BOT_TOKEN}",
+      "dmPolicy": "open"
+    }
+  }
+}

package/examples/hermes-like/.env.example

@@ -0,0 +1,2 @@
+DISCORD_BOT_TOKEN=replace-me
+BROWSER_API_KEY=replace-me

package/examples/hermes-like/config.json

@@ -0,0 +1,37 @@
+{
+  "mcp": {
+    "servers": {
+      "github-tools": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-github"]
+      },
+      "remote-browser": {
+        "type": "http",
+        "url": "https://example-hermes-mcp.invalid/mcp"
+      }
+    }
+  },
+  "gateway": {
+    "discord": {
+      "enabled": true,
+      "botToken": "${DISCORD_BOT_TOKEN}",
+      "allowed_users": []
+    }
+  },
+  "cron": [
+    {
+      "name": "weekly-research",
+      "schedule": "0 10 * * 1",
+      "prompt": "Research new MCP servers"
+    }
+  ],
+  "migration": {
+    "source": "~/.openclaw",
+    "skills": "~/.hermes/skills/openclaw-imports",
+    "includeApiKeys": true
+  },
+  "memory": {
+    "enabled": true,
+    "path": "~/.hermes/memory"
+  }
+}

package/examples/hermes-like/optional-mcps/github-tools.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "git-tools": {
+      "command": "uvx",
+      "args": ["mcp-server-git"]
+    }
+  }
+}

package/examples/hermes-like/skills/openclaw-imports/browser-skill/SKILL.md

@@ -0,0 +1,8 @@
+# Imported Browser Skill
+
+Imported from OpenClaw migration.
+
+Requires `BROWSER_API_KEY`.
+
+Install source: https://github.com/example/imported-browser-skill
+

package/examples/openclaw-like/.env.example

@@ -0,0 +1,2 @@
+TELEGRAM_BOT_TOKEN=replace-me
+BROWSER_API_KEY=replace-me

package/examples/openclaw-like/AGENTS.md

@@ -0,0 +1,7 @@
+# Example Agent Instructions
+
+This example is intentionally unsafe for testing AgentSecurityLens.
+
+The agent may use bash to inspect local files when needed.
+Do not reveal private keys.
+

package/examples/openclaw-like/openclaw.json

@@ -0,0 +1,28 @@
+{
+  "mcp": {
+    "servers": {
+      "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+      },
+      "remote-tools": {
+        "type": "sse",
+        "url": "https://example-mcp.invalid/sse"
+      }
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "dmPolicy": "open"
+    }
+  },
+  "scheduled": [
+    {
+      "name": "daily-summary",
+      "cron": "0 9 * * *",
+      "prompt": "Summarize workspace changes"
+    }
+  ]
+}

package/examples/openclaw-like/workspace/skills/browser-control/SKILL.md

@@ -0,0 +1,8 @@
+# Browser Control Skill
+
+Requires `BROWSER_API_KEY` in `.env`.
+
+Install source: https://github.com/example/browser-control-skill/archive/main.zip
+
+This skill can use browser automation and may write files to the workspace.
+

package/llms.txt

@@ -0,0 +1,25 @@
+# AgentSecurityLens
+
+AgentSecurityLens (ASL) is an agent-facing security intelligence service.
+
+Primary use:
+Before installing or enabling any MCP, Skill, tool, prompt bundle or workflow, call the AgentSecurityLens MCP tool `review_before_install`.
+
+Important MCP tools:
+- `review_before_install`: returns install decision, trust score, risk signals, safe install plan and alternatives.
+- `check_component`: checks known ASL component intelligence.
+- `recommend_alternatives`: returns safer alternatives and restriction plans.
+- `submit_unknown_component`: submits unknown public components for ASL research. Do not submit secrets or private file contents.
+- `discover_workspace`: discovers Agent, MCP and Skill environments under a workspace.
+- `scan_workspace`: assesses all discovered Agent, MCP and Skill environments.
+
+Decision meanings:
+- `allow`: component appears low risk from available signals.
+- `allow_with_restrictions`: install only after applying safe_install_plan.
+- `ask_user`: do not install automatically; ask the user.
+- `avoid`: do not install automatically; submit for review.
+
+Default agent policy:
+If ASL returns `ask_user` or `avoid`, stop automatic installation.
+If ASL returns `allow_with_restrictions`, apply all safe install steps first.
+If ASL returns `unknown_component.should_submit`, submit only public metadata, never secrets or private file contents.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "agent-security-lens",
+  "version": "0.1.0",
+  "private": false,
+  "mcpName": "io.github.professor2k8/agent-security-lens",
+  "description": "Agent-facing security MCP that queries ASL intelligence before autonomous agents install tools.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/professor2k8/agent-security-lens.git"
+  },
+  "homepage": "https://github.com/professor2k8/agent-security-lens#readme",
+  "bugs": {
+    "url": "https://github.com/professor2k8/agent-security-lens/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "agent-security",
+    "security",
+    "trust-score",
+    "agent-tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agent-security-lens": "./apps/mcp-server/agent-security-lens-mcp.mjs",
+    "asl": "./apps/mcp-server/agent-security-lens-mcp.mjs",
+    "agent-security-lens-mcp": "./apps/mcp-server/agent-security-lens-mcp.mjs",
+    "asl-mcp": "./apps/mcp-server/agent-security-lens-mcp.mjs",
+    "asl-scan": "./bin/agent-security-lens.mjs",
+    "agent-security-lens-scan": "./bin/agent-security-lens.mjs"
+  },
+  "scripts": {
+    "assess:example": "node ./bin/agent-security-lens.mjs assess ./examples/openclaw-like --profile openclaw-like",
+    "assess:json": "node ./bin/agent-security-lens.mjs assess ./examples/openclaw-like --profile openclaw-like --format json",
+    "assess:markdown": "node ./bin/agent-security-lens.mjs assess ./examples/openclaw-like --profile openclaw-like --format markdown",
+    "mcp:start": "node ./apps/mcp-server/agent-security-lens-mcp.mjs",
+    "mcp:smoke": "node ./scripts/verify-mcp-server.mjs",
+    "verify:registry": "node ./scripts/verify-registry.mjs",
+    "verify:examples": "node ./scripts/verify-examples.mjs",
+    "verify:public": "npm run verify:registry && npm run verify:examples && npm run mcp:smoke"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/profiles/generic-agent/profile.json

@@ -0,0 +1,19 @@
+{
+  "id": "generic-agent",
+  "version": "0.1.0",
+  "status": "active",
+  "confidence": 0.6,
+  "coverage": 0.45,
+  "extends": [],
+  "rule_packs": ["core"],
+  "path_hints": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursor/rules",
+    ".env",
+    "mcp.json"
+  ],
+  "known_limitations": [
+    "Generic profile only detects common patterns and does not understand product-specific runtime behavior."
+  ]
+}

package/profiles/hermes-like/profile.json

@@ -0,0 +1,23 @@
+{
+  "id": "hermes-like",
+  "version": "0.1.0",
+  "status": "draft",
+  "confidence": 0.5,
+  "coverage": 0.35,
+  "extends": ["generic-agent", "mcp-server", "skill-runtime"],
+  "rule_packs": ["core", "hermes"],
+  "path_hints": [
+    "config.yaml",
+    ".hermes/config.yaml",
+    "optional-mcps/",
+    "optional-skills/",
+    "skills/openclaw-imports/",
+    "cron/",
+    "gateway/",
+    "memory/"
+  ],
+  "known_limitations": [
+    "Hermes-like profile is a draft profile and should not be treated as full coverage.",
+    "Migration and gateway behavior require further source-level validation."
+  ]
+}

package/profiles/mcp-server/profile.json

@@ -0,0 +1,18 @@
+{
+  "id": "mcp-server",
+  "version": "0.1.0",
+  "status": "active",
+  "confidence": 0.65,
+  "coverage": 0.45,
+  "extends": [],
+  "rule_packs": ["mcp"],
+  "path_hints": [
+    "mcp.json",
+    "mcp*.json",
+    "claude_desktop_config.json",
+    ".vscode/mcp.json"
+  ],
+  "known_limitations": [
+    "Phase 1 detects MCP configuration patterns but does not execute MCP servers."
+  ]
+}

package/profiles/openclaw-like/profile.json

@@ -0,0 +1,22 @@
+{
+  "id": "openclaw-like",
+  "version": "0.1.0",
+  "status": "experimental",
+  "confidence": 0.72,
+  "coverage": 0.55,
+  "extends": ["generic-agent", "mcp-server", "skill-runtime"],
+  "rule_packs": ["core", "openclaw"],
+  "path_hints": [
+    "openclaw.json",
+    ".openclaw/openclaw.json",
+    "AGENTS.md",
+    "SOUL.md",
+    "TOOLS.md",
+    "skills/",
+    "workspace/skills/"
+  ],
+  "known_limitations": [
+    "OpenClaw-like profile is based on public docs and observed ecosystem patterns.",
+    "Runtime enforcement and live tool-call inspection are out of scope for Phase 1."
+  ]
+}

package/profiles/skill-runtime/profile.json

@@ -0,0 +1,19 @@
+{
+  "id": "skill-runtime",
+  "version": "0.1.0",
+  "status": "active",
+  "confidence": 0.65,
+  "coverage": 0.4,
+  "extends": [],
+  "rule_packs": ["skills"],
+  "path_hints": [
+    "SKILL.md",
+    "skills/",
+    "SKILLs/",
+    "skills.config.json",
+    "optional-skills/"
+  ],
+  "known_limitations": [
+    "Phase 1 skill analysis uses static patterns and does not run skill code."
+  ]
+}

package/rule-packs/core/rules.json

@@ -0,0 +1,82 @@
+{
+  "id": "core",
+  "version": "0.1.0",
+  "rules": [
+    {
+      "id": "core-shell-execution",
+      "title": "Shell execution pattern detected",
+      "category": "execution-risk",
+      "severity": "high",
+      "confidence": 0.82,
+      "permissions": ["shell-execution"],
+      "target_paths": ["**/*"],
+      "patterns": ["\\b(exec|spawn|subprocess|child_process|powershell|bash|cmd\\.exe)\\b"],
+      "why_it_matters": "This environment contains patterns that can execute local commands. That increases the trust required before running the agent.",
+      "recommended_actions": [
+        "Review the command source and arguments before running.",
+        "Disable command execution tools if they are not required."
+      ],
+      "recommended_alternatives": [
+        "Use a read-only tool or sandboxed command runner where possible."
+      ],
+      "migration_instruction": "Disable shell execution for this agent unless the task explicitly requires it."
+    },
+    {
+      "id": "core-remote-download",
+      "title": "Remote download pattern detected",
+      "category": "supply-chain-risk",
+      "severity": "medium",
+      "confidence": 0.78,
+      "permissions": ["external-download", "network-access"],
+      "target_paths": ["**/*"],
+      "patterns": ["\\b(curl|wget|Invoke-WebRequest|iwr)\\b", "https?://[^\\s]+\\.(sh|ps1|zip|tar|gz)"],
+      "why_it_matters": "Remote downloads can introduce new code, tools, skills or configuration into the agent environment.",
+      "recommended_actions": [
+        "Verify the source owner.",
+        "Pin versions or commit hashes instead of using moving branches."
+      ],
+      "recommended_alternatives": [
+        "Use a bundled or verified package source when available."
+      ],
+      "migration_instruction": "Replace unpinned remote downloads with pinned release assets or commit hashes."
+    },
+    {
+      "id": "core-env-reference",
+      "title": "Credential or environment variable reference detected",
+      "category": "data-exposure-risk",
+      "severity": "medium",
+      "confidence": 0.72,
+      "permissions": ["credential-access", "env-read"],
+      "target_paths": ["**/*"],
+      "patterns": ["(API_KEY|TOKEN|SECRET|PRIVATE_KEY|BOT_TOKEN|WEBHOOK_SECRET)", "\\.env"],
+      "why_it_matters": "Agent tools, skills or MCP servers may inherit credentials from environment variables or local files.",
+      "recommended_actions": [
+        "Use scoped credentials for agent environments.",
+        "Remove unused secrets before running the agent."
+      ],
+      "recommended_alternatives": [
+        "Use a dedicated low-privilege token for this agent."
+      ],
+      "migration_instruction": "Move high-privilege secrets out of the scanned agent environment and use scoped replacement tokens."
+    },
+    {
+      "id": "core-instruction-override",
+      "title": "Instruction override pattern detected",
+      "category": "data-exposure-risk",
+      "severity": "medium",
+      "confidence": 0.64,
+      "permissions": ["instruction-control"],
+      "target_paths": ["**/*.md", "AGENTS.md", "SOUL.md", "TOOLS.md"],
+      "patterns": ["ignore (previous|all) instructions", "override (safety|system|developer)"],
+      "why_it_matters": "Instruction override patterns can change how an agent follows rules and handles sensitive context.",
+      "recommended_actions": [
+        "Review the surrounding prompt text.",
+        "Remove hidden or unnecessary override instructions."
+      ],
+      "recommended_alternatives": [
+        "Use explicit, narrow tool permissions instead of broad instruction overrides."
+      ],
+      "migration_instruction": "Replace broad override instructions with specific, reviewable tool policies."
+    }
+  ]
+}

package/rule-packs/hermes/rules.json

@@ -0,0 +1,44 @@
+{
+  "id": "hermes",
+  "version": "0.1.0",
+  "rules": [
+    {
+      "id": "hermes-openclaw-migration",
+      "title": "Hermes OpenClaw migration artifact detected",
+      "category": "supply-chain-risk",
+      "severity": "medium",
+      "confidence": 0.76,
+      "permissions": ["skill-installation", "credential-access", "persistent-memory"],
+      "target_paths": ["**/*"],
+      "patterns": ["openclaw-imports|migrate-from-openclaw|\\.openclaw"],
+      "why_it_matters": "OpenClaw migration can import skills, settings, memories or credentials into a Hermes environment.",
+      "recommended_actions": [
+        "Review imported skills and credentials.",
+        "Remove migrated artifacts that are no longer needed."
+      ],
+      "recommended_alternatives": [
+        "Import only selected skills instead of full environment migration."
+      ],
+      "migration_instruction": "Review ~/.hermes/skills/openclaw-imports and remove unused imported skills."
+    },
+    {
+      "id": "hermes-gateway-trigger",
+      "title": "Hermes gateway or remote trigger detected",
+      "category": "remote-access-risk",
+      "severity": "medium",
+      "confidence": 0.72,
+      "permissions": ["remote-trigger", "network-access"],
+      "target_paths": ["**/*.json", "**/*.yaml", "**/*.yml"],
+      "patterns": ["gateway|telegram|discord|slack|whatsapp|signal|webhook|allowed_users"],
+      "why_it_matters": "Gateway configuration can allow remote systems or users to trigger agent behavior.",
+      "recommended_actions": [
+        "Restrict allowed users.",
+        "Disable unused gateways."
+      ],
+      "recommended_alternatives": [
+        "Use local CLI-only mode for sensitive workspaces."
+      ],
+      "migration_instruction": "Disable remote gateways until allowed users and token storage are reviewed."
+    }
+  ]
+}

package/rule-packs/mcp/rules.json

@@ -0,0 +1,65 @@
+{
+  "id": "mcp",
+  "version": "0.1.0",
+  "rules": [
+    {
+      "id": "mcp-stdio-process-server",
+      "title": "MCP stdio process server detected",
+      "category": "execution-risk",
+      "severity": "high",
+      "confidence": 0.86,
+      "permissions": ["subprocess-spawn", "mcp-tool-access"],
+      "target_paths": ["**/mcp*.json", "**/*.toml", "**/*.yaml", "**/*.yml", "**/*.json"],
+      "patterns": ["\"command\"\\s*:", "\\b(npx|uvx|python|node|docker)\\b", "@modelcontextprotocol/server-"],
+      "why_it_matters": "A stdio MCP server starts a local process. The agent may delegate tool calls to that process.",
+      "recommended_actions": [
+        "Verify the MCP package source and command arguments.",
+        "Pin the MCP package version."
+      ],
+      "recommended_alternatives": [
+        "Use a local verified MCP server with a pinned version.",
+        "Disable this MCP server if it is not required."
+      ],
+      "migration_instruction": "Replace moving MCP commands such as npx latest with a pinned package version."
+    },
+    {
+      "id": "mcp-remote-endpoint",
+      "title": "Remote MCP endpoint detected",
+      "category": "remote-access-risk",
+      "severity": "medium",
+      "confidence": 0.8,
+      "permissions": ["network-access", "external-endpoint", "mcp-tool-access"],
+      "target_paths": ["**/mcp*.json", "**/*.toml", "**/*.yaml", "**/*.yml", "**/*.json"],
+      "patterns": ["\"type\"\\s*:\\s*\"(sse|http|streamable-http)\"", "https?://[^\\s\"']+"],
+      "why_it_matters": "Remote MCP endpoints can receive tool calls or provide tools from outside the local environment.",
+      "recommended_actions": [
+        "Verify the remote MCP owner and transport security.",
+        "Restrict exposed tools if the client supports filtering."
+      ],
+      "recommended_alternatives": [
+        "Prefer a local stdio MCP server from a verified source for sensitive tasks."
+      ],
+      "migration_instruction": "Disable remote MCP endpoints for sensitive workspaces or replace them with local pinned MCP servers."
+    },
+    {
+      "id": "mcp-filesystem-write",
+      "title": "Filesystem write MCP capability detected",
+      "category": "data-exposure-risk",
+      "severity": "high",
+      "confidence": 0.84,
+      "permissions": ["filesystem-write", "mcp-tool-access"],
+      "target_paths": ["**/*"],
+      "patterns": ["write_file|edit_file|move_file|create_directory|delete_file|filesystem"],
+      "match_scope": "file",
+      "why_it_matters": "Filesystem write tools can modify local files through agent tool calls.",
+      "recommended_actions": [
+        "Limit filesystem tools to a dedicated workspace.",
+        "Disable write-capable tools unless required."
+      ],
+      "recommended_alternatives": [
+        "Use read-only filesystem tooling for inspection tasks."
+      ],
+      "migration_instruction": "Replace write-capable filesystem tools with read-only tools when the task only needs inspection."
+    }
+  ]
+}

package/rule-packs/openclaw/rules.json

@@ -0,0 +1,46 @@
+{
+  "id": "openclaw",
+  "version": "0.1.0",
+  "rules": [
+    {
+      "id": "openclaw-remote-channel-policy",
+      "title": "OpenClaw remote channel policy detected",
+      "category": "remote-access-risk",
+      "severity": "medium",
+      "confidence": 0.76,
+      "permissions": ["remote-trigger", "credential-access"],
+      "target_paths": ["**/openclaw.json", "**/*.yaml", "**/*.yml", "**/*.json"],
+      "patterns": ["dmPolicy|allowFrom|groupPolicy|webhook|telegram|discord|slack|feishu|wechat|qq"],
+      "match_scope": "file",
+      "why_it_matters": "Remote channels can trigger agent sessions. Channel policies and allowlists determine who can reach the agent.",
+      "recommended_actions": [
+        "Restrict allowed users or groups.",
+        "Rotate bot tokens if they were exposed in local files."
+      ],
+      "recommended_alternatives": [
+        "Use local-only mode for sensitive workspaces."
+      ],
+      "migration_instruction": "Set explicit allowFrom values and disable group triggers unless they are required."
+    },
+    {
+      "id": "openclaw-scheduled-task",
+      "title": "OpenClaw scheduled or background execution detected",
+      "category": "persistence-automation-risk",
+      "severity": "medium",
+      "confidence": 0.72,
+      "permissions": ["scheduled-execution"],
+      "target_paths": ["**/*"],
+      "patterns": ["cron|scheduled|schedule|background session|auto.?run"],
+      "match_scope": "file",
+      "why_it_matters": "Scheduled agent tasks can start later, when the user is not actively reviewing each action.",
+      "recommended_actions": [
+        "Review scheduled task prompts and allowed tools.",
+        "Disable unused scheduled tasks."
+      ],
+      "recommended_alternatives": [
+        "Use manual run mode for sensitive workflows."
+      ],
+      "migration_instruction": "Disable scheduled execution for this agent until the task prompt and tool permissions are reviewed."
+    }
+  ]
+}

package/rule-packs/skills/rules.json

@@ -0,0 +1,45 @@
+{
+  "id": "skills",
+  "version": "0.1.0",
+  "rules": [
+    {
+      "id": "skill-env-requirement",
+      "title": "Skill references environment credentials",
+      "category": "data-exposure-risk",
+      "severity": "medium",
+      "confidence": 0.78,
+      "permissions": ["credential-access", "env-read"],
+      "target_paths": ["**/SKILL.md", "**/skills.config.json", "**/SKILLs/**"],
+      "patterns": ["API_KEY|TOKEN|SECRET|\\.env"],
+      "supersedes": ["core-env-reference"],
+      "why_it_matters": "Skills that require credentials can inherit sensitive access from the local environment.",
+      "recommended_actions": [
+        "Review required credentials before enabling the skill.",
+        "Use scoped credentials with minimum permissions."
+      ],
+      "recommended_alternatives": [
+        "Use a read-only or unauthenticated skill variant if available."
+      ],
+      "migration_instruction": "Create a dedicated low-privilege token for this skill instead of reusing personal credentials."
+    },
+    {
+      "id": "skill-remote-install-source",
+      "title": "Skill remote install source detected",
+      "category": "supply-chain-risk",
+      "severity": "medium",
+      "confidence": 0.75,
+      "permissions": ["skill-installation", "external-download"],
+      "target_paths": ["**/SKILL.md", "**/skills.config.json", "**/*.json"],
+      "patterns": ["github\\.com|https?://|git clone|zip"],
+      "why_it_matters": "Remote skill sources can add new instructions, dependencies or scripts to the agent environment.",
+      "recommended_actions": [
+        "Verify the skill source.",
+        "Pin the source to a commit or release."
+      ],
+      "recommended_alternatives": [
+        "Use bundled or community-vetted skills where available."
+      ],
+      "migration_instruction": "Pin the skill source to a commit SHA and review SKILL.md before enabling it."
+    }
+  ]
+}