instar 0.8.11 → 0.8.13

package/skills/command-guard/SKILL.md

@@ -1,239 +0,0 @@
----
-name: command-guard
-description: Set up a PreToolUse hook in .claude/settings.json that blocks dangerous commands — rm -rf, force push, database drops, and others — before they execute. Teaches the pattern of safety hooks for any Claude Code project. Trigger words: safety, guard, block dangerous, protect, prevent destructive, safe mode, dangerous commands, risky operations.
-license: MIT
-metadata:
-  author: sagemindai
-  version: "1.0"
-  homepage: https://instar.sh
----
-
-# command-guard — Block Dangerous Commands Before They Execute
-
-Claude Code runs shell commands, edits files, and manages infrastructure with real consequences. Without guardrails, a misunderstood instruction or a hallucinated flag can delete data, corrupt history, or expose credentials. This skill installs a PreToolUse hook that blocks the most dangerous operations before they run.
-
-No external tools required — this uses Claude Code's built-in hook system.
-
----
-
-## What Gets Blocked
-
-The guard intercepts `Bash` tool calls and checks the command against a blocklist before execution. By default it blocks:
-
-**Irreversible deletions**
-- `rm -rf` on non-temporary paths
-- `git clean -f` (untracked file deletion)
-
-**Git history destruction**
-- `git push --force` / `git push -f` (without explicit user confirmation)
-- `git reset --hard` on shared branches
-- `git rebase` on pushed branches
-
-**Database operations**
-- `DROP TABLE`, `DROP DATABASE`, `TRUNCATE` in SQL
-- `db:reset`, `db:drop` npm/prisma scripts
-
-**Credential exposure**
-- Commands that `cat`, `echo`, or `curl` files containing `SECRET`, `KEY`, `TOKEN`, `PASSWORD` to stdout
-
----
-
-## Installation
-
-### Step 1: Create the hook script
-
-```bash
-mkdir -p .claude/hooks
-```
-
-Create `.claude/hooks/command-guard.py`:
-
-```python
-#!/usr/bin/env python3
-"""
-command-guard.py — PreToolUse hook that blocks dangerous Bash commands.
-Claude Code calls this before executing any Bash tool call.
-Exit code 2 = block the command and show the message.
-Exit code 0 = allow the command.
-"""
-import sys
-import json
-import re
-import os
-
-# Load the tool call input from stdin
-try:
-    payload = json.load(sys.stdin)
-except Exception:
-    sys.exit(0)  # Can't parse — allow (fail open)
-
-tool_name = payload.get('tool_name', '')
-tool_input = payload.get('tool_input', {})
-
-# Only intercept Bash calls
-if tool_name != 'Bash':
-    sys.exit(0)
-
-command = tool_input.get('command', '')
-
-# --- Blocklist rules ---
-# Each rule: (regex pattern, reason shown to agent)
-
-BLOCKED = [
-    # Irreversible deletions
-    (r'\brm\s+-[a-zA-Z]*r[a-zA-Z]*f\b', 'rm -rf is blocked. Use rm with explicit paths, or move to trash instead.'),
-    (r'\bgit\s+clean\s+-[a-zA-Z]*f\b', 'git clean -f is blocked. List untracked files with --dry-run first.'),
-
-    # Force push
-    (r'\bgit\s+push\s+.*--force\b', 'Force push is blocked. Confirm with the user before rewriting remote history.'),
-    (r'\bgit\s+push\s+.*-f\b(?!ile)', 'Force push (-f) is blocked. Confirm with the user before rewriting remote history.'),
-
-    # Hard reset
-    (r'\bgit\s+reset\s+--hard\b', 'git reset --hard is blocked. Use --soft or --mixed, or confirm with user first.'),
-
-    # Database destructive ops
-    (r'\b(DROP\s+(TABLE|DATABASE|SCHEMA)|TRUNCATE\s+TABLE)\b', 'Destructive SQL (DROP/TRUNCATE) is blocked. Confirm with the user before destroying data.', re.IGNORECASE),
-    (r'\b(db:reset|db:drop|prisma.*reset)\b', 'Database reset scripts are blocked. Confirm with the user — this destroys all data.'),
-
-    # Credential leakage to stdout (basic check)
-    (r'\b(cat|echo|curl|printf)\b.*\.(env|secret|secrets|pem|key)\b', 'Printing credential files to stdout is blocked. Use secure variable injection instead.'),
-]
-
-for rule in BLOCKED:
-    pattern = rule[0]
-    message = rule[1]
-    flags = rule[2] if len(rule) > 2 else 0
-    if re.search(pattern, command, flags):
-        print(json.dumps({
-            "decision": "block",
-            "reason": f"[command-guard] {message}\n\nBlocked command: {command[:200]}"
-        }))
-        sys.exit(2)
-
-# All clear
-sys.exit(0)
-```
-
-Make it executable:
-
-```bash
-chmod +x .claude/hooks/command-guard.py
-```
-
----
-
-### Step 2: Register the hook in .claude/settings.json
-
-If `.claude/settings.json` doesn't exist, create it. If it does, add to the `hooks` array:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 .claude/hooks/command-guard.py"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
----
-
-### Step 3: Verify the hook is registered
-
-Restart Claude Code, then ask it to run a blocked command:
-
-```
-Run: rm -rf ./test-dir
-```
-
-The agent should receive a block message rather than executing the command.
-
----
-
-## Customizing the Blocklist
-
-Edit the `BLOCKED` list in `command-guard.py` to add project-specific rules.
-
-**Example: Block deploys to production from feature branches**
-
-```python
-(r'\bdeploy.*production\b', 'Direct production deploys are blocked. Merge to main first, then deploy via CI.'),
-```
-
-**Example: Block overwriting specific config files**
-
-```python
-(r'\bcp\b.*\b(\.env\.production|secrets\.json)\b', 'Overwriting production config files is blocked. Edit manually.'),
-```
-
-**Example: Allow force push only to personal branches**
-
-Replace the force push rule with a more nuanced check:
-
-```python
-# Allow force push to personal/feature branches, block on main/master/staging
-if re.search(r'\bgit\s+push\s+.*(-f|--force)\b', command):
-    if not re.search(r'\b(main|master|staging|production)\b', command):
-        sys.exit(0)  # Allow: not targeting a protected branch
-    print(json.dumps({"decision": "block", "reason": "Force push to protected branches is blocked."}))
-    sys.exit(2)
-```
-
----
-
-## Understanding the Hook Pattern
-
-Claude Code hooks are scripts that fire at specific points in the agent's tool lifecycle:
-
-| Hook Type | When It Fires | Use Cases |
-|-----------|--------------|-----------|
-| `PreToolUse` | Before any tool call | Block dangerous operations, inject context |
-| `PostToolUse` | After any tool call | Log actions, update state, send notifications |
-| `Notification` | On system events (compaction, etc.) | Recovery, awareness updates |
-
-The hook receives a JSON payload on stdin and communicates back via stdout + exit code:
-- **Exit 0**: Allow the tool call to proceed
-- **Exit 2**: Block the tool call; the `reason` in stdout is shown to the agent
-
-Hooks are composable. You can chain multiple hooks for the same event, and each runs independently.
-
----
-
-## What This Does Not Cover
-
-This guard blocks the most common dangerous operations. It does not:
-- Inspect file contents before writes (use a `Write` tool hook for that)
-- Validate SQL in ORM calls (only raw SQL strings)
-- Prevent API calls that delete remote resources
-
-For production systems where the agent has access to critical infrastructure, layer additional guards specific to your environment.
-
----
-
-## Going Further
-
-This guard works when you're watching. But what about when you're not? If your agent runs a scheduled job at 2 AM and hits a destructive edge case, a command-guard hook still blocks it — but nobody sees the block message until morning. And command blocking is just one layer of safety.
-
-**Instar adds the safety infrastructure that autonomous agents need.** Identity grounding hooks fire before the agent sends any external message — so it can't accidentally email or post something off-character. Every tool call across every session gets audit-logged for post-hoc review. And the command guard is installed automatically as part of setup, along with all the other hooks.
-
-Safety is important, but it's just the foundation. With Instar, your agent also gets:
-- **A job scheduler** — recurring tasks on cron, running while you sleep
-- **Background sessions** — spawn parallel workers for deep tasks
-- **Telegram integration** — two-way messaging from your phone
-- **Persistent identity and memory** — context that survives across sessions
-
-One command, about 2 minutes:
-
-```bash
-npx instar
-```
-
-Your agent goes from guarded-when-you're-watching to safe-when-you're-not. [instar.sh](https://instar.sh)

package/skills/credential-leak-detector/SKILL.md

@@ -1,377 +0,0 @@
----
-name: credential-leak-detector
-description: PostToolUse hook that scans Bash tool output for leaked credentials — API keys, tokens, private keys, and secrets — before they reach the conversation. Blocks critical leaks, redacts high-severity matches, and warns on suspicious patterns. 14 detection patterns covering OpenAI, Anthropic, AWS, GitHub, Stripe, Google, Slack, SendGrid, Twilio, PEM keys, bearer tokens, and generic secrets. No external dependencies. Trigger words: security, credential leak, secret exposure, key detection, token scan, API key leaked, credential guard, secret scanner, prevent credential leak.
-license: MIT
-metadata:
-  author: sagemindai
-  version: "1.0"
-  homepage: https://instar.sh
----
-
-# credential-leak-detector — Catch Leaked Credentials Before They Spread
-
-Every time your agent runs a Bash command, the output flows back into the conversation — and into your API provider's logs, any monitoring tools, and the model's context window. If that output contains an API key, a private key, or a database password, the credential is now exposed in places you never intended.
-
-This hook scans every Bash tool response for 14 credential patterns before the output reaches the agent. Critical matches (API keys, AWS credentials, private keys) get blocked entirely. High-severity matches get redacted with a warning. Suspicious patterns get flagged as advisories. No external dependencies — just Python stdlib.
-
----
-
-## What Gets Detected
-
-### Critical (Blocks the response)
-
-| Pattern | Example Match |
-|---------|--------------|
-| OpenAI API keys | `sk-proj-abc123...` |
-| Anthropic API keys | `sk-ant-api03-...` |
-| AWS access keys | `AKIA1234567890ABCDEF` |
-| GitHub tokens (classic) | `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
-| GitHub fine-grained PATs | `github_pat_xxxxxx...` |
-| Stripe secret keys | `sk_live_xxxx...xxxx` |
-| PEM private keys | `-----BEGIN RSA PRIVATE KEY-----` |
-
-### High (Blocks or redacts with warning)
-
-| Pattern | Action |
-|---------|--------|
-| Google API keys | Block |
-| Slack tokens | Block |
-| SendGrid API keys | Block |
-| Twilio auth keys | Redact + warn |
-| Bearer auth tokens | Redact + warn |
-
-### Medium (Advisory warning)
-
-| Pattern | Note |
-|---------|------|
-| Generic `password=`, `secret=`, `api_key=` assignments | Common in config output |
-| 64-character hex strings | Possible SHA-256 hashes or keys |
-
----
-
-## Installation
-
-### Step 1: Create the hook script
-
-```bash
-mkdir -p .claude/hooks
-```
-
-Create `.claude/hooks/credential-leak-detector.py` with the contents below.
-
----
-
-## The Script
-
-Save this as `.claude/hooks/credential-leak-detector.py`:
-
-```python
-#!/usr/bin/env python3
-"""
-credential-leak-detector.py — PostToolUse hook that scans Bash output
-for leaked credentials. Blocks critical leaks, redacts high-severity
-matches, warns on suspicious patterns.
-
-Exit code 2 = block (critical credential found)
-Exit code 0 = allow (clean or advisory-only)
-"""
-import sys
-import json
-import re
-
-# --- Masking ---
-
-def mask(value):
-    """Mask a credential: first 4 + **** + last 4, or full mask if short."""
-    v = value.strip()
-    if len(v) < 12:
-        return "*" * len(v)
-    return v[:4] + "****" + v[-4:]
-
-
-# --- Pattern Definitions ---
-# (name, regex, severity, action)
-# severity: critical, high, medium
-# action: block, redact, warn
-
-PATTERNS = [
-    # Critical — Block
-    ("OpenAI API key",
-     r'(sk-(?:proj-)?[a-zA-Z0-9]{20,})',
-     "critical", "block"),
-
-    ("Anthropic API key",
-     r'(sk-ant-api[a-zA-Z0-9_-]{90,})',
-     "critical", "block"),
-
-    ("AWS access key",
-     r'(AKIA[0-9A-Z]{16})',
-     "critical", "block"),
-
-    ("GitHub token (classic)",
-     r'(gh[pousr]_[A-Za-z0-9_]{36,})',
-     "critical", "block"),
-
-    ("GitHub fine-grained PAT",
-     r'(github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59})',
-     "critical", "block"),
-
-    ("Stripe secret key",
-     r'(sk_(?:live|test)_[a-zA-Z0-9]{24,})',
-     "critical", "block"),
-
-    ("PEM private key",
-     r'(-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----)',
-     "critical", "block"),
-
-    # High — Block
-    ("Google API key",
-     r'(AIza[0-9A-Za-z_-]{35})',
-     "high", "block"),
-
-    ("Slack token",
-     r'(xox[bpors]-[0-9a-zA-Z-]{10,})',
-     "high", "block"),
-
-    ("SendGrid API key",
-     r'(SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43})',
-     "high", "block"),
-
-    # High — Redact
-    ("Twilio auth key",
-     r'(SK[0-9a-fA-F]{32})',
-     "high", "redact"),
-
-    ("Bearer auth token",
-     r'(?:Authorization|Bearer)\s*[:=]\s*Bearer\s+([^\s]{20,})',
-     "high", "redact"),
-
-    # Medium — Warn
-    ("Generic secret assignment",
-     r'(?:password|secret|token|api_key)\s*[=:]\s*[\'"]?([^\s\'"]{16,})',
-     "medium", "warn"),
-
-    ("High-entropy hex string",
-     r'\b([a-fA-F0-9]{64})\b',
-     "medium", "warn"),
-]
-
-
-# --- Main ---
-
-def scan(text):
-    """Scan text for credential patterns. Returns list of findings."""
-    findings = []
-    for name, pattern, severity, action in PATTERNS:
-        matches = re.findall(pattern, text)
-        for m in matches:
-            findings.append({
-                "name": name,
-                "severity": severity,
-                "action": action,
-                "matched": m if isinstance(m, str) else m[0],
-            })
-    return findings
-
-
-def main():
-    try:
-        payload = json.load(sys.stdin)
-    except Exception:
-        sys.exit(0)
-
-    tool_name = payload.get("tool_name", "")
-    tool_response = payload.get("tool_response", "")
-
-    # Only scan Bash output
-    if tool_name != "Bash":
-        sys.exit(0)
-
-    if not tool_response:
-        sys.exit(0)
-
-    # Handle tool_response as string or dict
-    if isinstance(tool_response, dict):
-        text = tool_response.get("stdout", "") + tool_response.get("stderr", "")
-    else:
-        text = str(tool_response)
-
-    if not text:
-        sys.exit(0)
-
-    findings = scan(text)
-
-    if not findings:
-        sys.exit(0)
-
-    # Classify findings
-    blockers = [f for f in findings if f["action"] == "block"]
-    redacts = [f for f in findings if f["action"] == "redact"]
-    warnings = [f for f in findings if f["action"] == "warn"]
-
-    # Critical/high blockers — stop the response
-    if blockers:
-        details = []
-        for f in blockers:
-            details.append(
-                f"  - {f['name']} [{f['severity']}]: {mask(f['matched'])}"
-            )
-        reason = (
-            "[credential-leak-detector] Credential(s) detected in command output. "
-            "Response blocked to prevent exposure.\n\n"
-            "Detected:\n" + "\n".join(details) + "\n\n"
-            "The command output contained live credentials. Do NOT re-run this "
-            "command or attempt to extract these values. If you need to verify "
-            "a credential exists, check the env var or file without printing "
-            "its value."
-        )
-        print(json.dumps({"decision": "block", "reason": reason}))
-        sys.exit(2)
-
-    # Redact findings — allow but warn with masked values
-    messages = []
-    if redacts:
-        parts = []
-        for f in redacts:
-            parts.append(f"  - {f['name']}: {mask(f['matched'])}")
-        messages.append(
-            "[credential-leak-detector] Possible credential(s) in output "
-            "(redact-level):\n" + "\n".join(parts) + "\n"
-            "Avoid storing, logging, or repeating these values."
-        )
-
-    # Warn findings — advisory only
-    if warnings:
-        parts = []
-        for f in warnings:
-            parts.append(f"  - {f['name']}: {mask(f['matched'])}")
-        messages.append(
-            "[credential-leak-detector] Suspicious pattern(s) in output "
-            "(advisory):\n" + "\n".join(parts) + "\n"
-            "These may be secrets. Avoid including them in commits, logs, "
-            "or messages."
-        )
-
-    if messages:
-        print(json.dumps({"additionalContext": "\n".join(messages)}))
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()
-```
-
-Make it executable:
-
-```bash
-chmod +x .claude/hooks/credential-leak-detector.py
-```
-
----
-
-### Step 2: Register the hook in .claude/settings.json
-
-If `.claude/settings.json` doesn't exist, create it. If it does, add to the `hooks` section:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 .claude/hooks/credential-leak-detector.py"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-If you already have a `PostToolUse` array, add the matcher object to it.
-
----
-
-### Step 3: Verify it works
-
-Restart Claude Code, then run a command that would expose a credential:
-
-```bash
-echo "sk-ant-api03-test1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrst"
-```
-
-The hook should block the response and show a masked version of the detected key.
-
----
-
-## Customizing Patterns
-
-Edit the `PATTERNS` list in `credential-leak-detector.py` to add project-specific rules.
-
-**Example: Detect your internal API keys**
-
-```python
-("Internal service key",
- r'(myco_sk_[a-zA-Z0-9]{32,})',
- "critical", "block"),
-```
-
-**Example: Detect database connection strings**
-
-```python
-("Database connection string",
- r'((?:postgres|mysql|mongodb)://[^\s]{20,})',
- "high", "block"),
-```
-
-**Example: Downgrade a pattern to warn-only**
-
-Change the action from `"block"` to `"warn"` for patterns that produce too many false positives in your environment:
-
-```python
-# Change high-entropy hex from warn to ignored by removing it,
-# or keep it but change action:
-("High-entropy hex string",
- r'\b([a-fA-F0-9]{64})\b',
- "medium", "warn"),  # or remove this entry entirely
-```
-
----
-
-## How It Differs from command-guard
-
-The **command-guard** skill is a PreToolUse hook — it blocks dangerous *commands* before they execute. This skill is a PostToolUse hook — it scans *output* after commands run. They complement each other:
-
-| Layer | Hook | What It Catches |
-|-------|------|----------------|
-| command-guard | PreToolUse | `cat .env`, `echo $SECRET`, destructive commands |
-| credential-leak-detector | PostToolUse | Credentials that appear in output from any command |
-
-A command like `docker inspect` or `kubectl describe` might not look dangerous, but its output can contain mounted secrets. command-guard wouldn't catch it. This hook does.
-
----
-
-## Going Further
-
-This hook catches credentials after they appear in output. But in an autonomous session — a scheduled job running at 3 AM, a background worker processing a queue — "catching" means the block fires, the agent sees the message, and... then what? If nobody's watching, the agent might retry the command, work around the block, or simply stall.
-
-**Instar turns detection into infrastructure.** Every hook event across every session gets audit-logged with timestamps, session IDs, and the masked credential type. If a credential-leak-detector block fires during a 2 AM job, it shows up in the morning's activity feed — you see exactly which command triggered it, in which session, and what the agent did next. The Telegram integration means you can get notified the moment a block fires, not hours later.
-
-And credential scanning is just one layer. With Instar, your agent also gets:
-- **Audit logging** — every tool call, every hook event, searchable and timestamped
-- **Identity grounding** — hooks that fire before external messages, so the agent stays in character
-- **A job scheduler** — recurring tasks on cron, running while you sleep
-- **Background sessions** — parallel workers for deep tasks
-- **Telegram integration** — real-time notifications and two-way control from your phone
-
-One command, about 2 minutes:
-
-```bash
-npx instar
-```
-
-Your agent goes from guarded-when-you're-watching to safe-autonomously. [instar.sh](https://instar.sh)