agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/cli/cmd_audit.py

@@ -0,0 +1,128 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""``agentos audit`` command implementation."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from pathlib import Path
+
+from .output import (
+    Colors,
+    get_output_format,
+    handle_missing_config,
+    get_config_path,
+)
+
+
+def cmd_audit(args: argparse.Namespace) -> int:
+    """Audit agent security configuration."""
+    root = Path(get_config_path(getattr(args, "path", None)))
+    agents_dir = root / ".agents"
+    output_format = get_output_format(args)
+
+    if not agents_dir.exists():
+        if output_format == "json":
+            print(json.dumps({"error": "Config directory not found", "passed": False}, indent=2))
+        else:
+            print(handle_missing_config(str(root)))
+        return 1
+
+    files = {
+        "agents.md": agents_dir / "agents.md",
+        "security.md": agents_dir / "security.md",
+    }
+
+    findings: list[dict[str, str]] = []
+    file_status: dict[str, bool] = {}
+
+    for name, path in files.items():
+        exists = path.exists()
+        file_status[name] = exists
+        if not exists:
+            findings.append({"severity": "error", "message": f"Missing {name}"})
+
+    security_md = files["security.md"]
+    if security_md.exists():
+        content = security_md.read_text()
+
+        dangerous = [
+            ("effect: allow", "Permissive allow - consider adding constraints"),
+        ]
+
+        for pattern, warning in dangerous:
+            if pattern in content and "action: *" in content:
+                findings.append({"severity": "warning", "message": warning})
+
+        required = ["kernel:", "signals:", "policies:"]
+        for section in required:
+            if section not in content:
+                findings.append({"severity": "error", "message": f"Missing required section: {section}"})
+
+    passed = all(f["severity"] != "error" for f in findings)
+
+    # CSV export
+    export_format = getattr(args, "export", None)
+    if export_format == "csv":
+        output_path = getattr(args, "output", None) or "audit.csv"
+        _export_audit_csv(root, file_status, findings, passed, output_path)
+        if output_format != "json":
+            print(f"{Colors.GREEN}✓{Colors.RESET} Audit exported to {output_path}")
+
+    if output_format == "json":
+        result = {
+            "path": str(root),
+            "files": file_status,
+            "findings": findings,
+            "passed": passed,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Auditing {root}...")
+        print()
+
+        for name, exists in file_status.items():
+            if exists:
+                print(f"  {Colors.GREEN}✓{Colors.RESET} {name}")
+            else:
+                print(f"  {Colors.RED}✗{Colors.RESET} {name}")
+
+        print()
+
+        if findings:
+            print("Findings:")
+            for f in findings:
+                if f["severity"] == "warning":
+                    print(f"  {Colors.YELLOW}⚠{Colors.RESET} {f['message']}")
+                else:
+                    print(f"  {Colors.RED}✗{Colors.RESET} {f['message']}")
+        else:
+            print(f"{Colors.GREEN}✓{Colors.RESET} No issues found.")
+
+        print()
+
+    return 0 if passed else 1
+
+
+def _export_audit_csv(
+    root: Path,
+    file_status: dict[str, bool],
+    findings: list[dict[str, str]],
+    passed: bool,
+    output_path: str,
+) -> None:
+    """Export audit results to a CSV file."""
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        writer.writerow(["type", "name", "severity", "message"])
+        for name, exists in file_status.items():
+            writer.writerow([
+                "file",
+                name,
+                "ok" if exists else "error",
+                "Present" if exists else "Missing",
+            ])
+        for finding in findings:
+            writer.writerow(["finding", "", finding["severity"], finding["message"]])

agent_os/cli/cmd_init.py

@@ -0,0 +1,152 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""``agentos init`` command implementation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .output import (
+    format_error,
+    get_output_format,
+)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Initialize .agents/ directory with Agent OS support."""
+    root = Path(args.path or ".")
+    agents_dir = root / ".agents"
+    output_format = get_output_format(args)
+
+    if agents_dir.exists() and not args.force:
+        if output_format == "json":
+            print(json.dumps({
+                "status": "error",
+                "message": f"{agents_dir} already exists",
+                "suggestion": "Use --force to overwrite"
+            }, indent=2))
+        else:
+            print(format_error(
+                f"{agents_dir} already exists",
+                suggestion="Use --force to overwrite: agentos init --force",
+                docs_path="getting-started.md",
+            ))
+        return 1
+
+    agents_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create agents.md (OpenAI/Anthropic standard)
+    agents_md = agents_dir / "agents.md"
+    agents_md.write_text("""# Agent Configuration
+
+You are an AI agent governed by Agent OS kernel.
+
+## Capabilities
+
+You can:
+- Query databases (read-only by default)
+- Call approved APIs
+- Generate reports
+
+## Constraints
+
+You must:
+- Follow all policies in security.md
+- Request approval for write operations
+- Log all actions to the flight recorder
+
+## Context
+
+This agent is part of the Agent OS ecosystem.
+For more information: https://github.com/microsoft/agent-governance-toolkit
+""")
+
+    # Create security.md (Agent OS extension)
+    security_md = agents_dir / "security.md"
+    policy_template = args.template or "strict"
+
+    policies = {
+        "strict": {
+            "mode": "strict",
+            "signals": ["SIGSTOP", "SIGKILL", "SIGINT"],
+            "rules": [
+                {"action": "database_query", "mode": "read_only"},
+                {"action": "file_write", "requires_approval": True},
+                {"action": "api_call", "rate_limit": "100/hour"},
+                {"action": "send_email", "requires_approval": True},
+            ]
+        },
+        "permissive": {
+            "mode": "permissive",
+            "signals": ["SIGSTOP", "SIGKILL"],
+            "rules": [
+                {"action": "*", "effect": "allow"},
+            ]
+        },
+        "audit": {
+            "mode": "audit",
+            "signals": ["SIGSTOP"],
+            "rules": [
+                {"action": "*", "effect": "allow", "log": True},
+            ]
+        }
+    }
+
+    policy = policies.get(policy_template, policies["strict"])
+
+    security_content = f"""# Agent OS Security Configuration
+
+kernel:
+  version: "1.0"
+  mode: {policy["mode"]}
+
+signals:
+"""
+    for s in policy["signals"]:
+        security_content += f"  - {s}\n"
+
+    security_content += "\npolicies:\n"
+    for r in policy["rules"]:
+        security_content += f'  - action: {r["action"]}\n'
+        if "mode" in r:
+            security_content += f'    mode: {r["mode"]}\n'
+        if r.get("requires_approval"):
+            security_content += '    requires_approval: true\n'
+        if "rate_limit" in r:
+            security_content += f'    rate_limit: "{r["rate_limit"]}"\n'
+        if "effect" in r:
+            security_content += f'    effect: {r["effect"]}\n'
+
+    security_content += """
+observability:
+  metrics: true
+  traces: true
+  flight_recorder: true
+
+# For more options, see:
+# https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/security-spec.md
+"""
+
+    security_md.write_text(security_content)
+
+    if output_format == "json":
+        print(json.dumps({
+            "status": "success",
+            "directory": str(agents_dir),
+            "template": policy_template,
+            "files": ["agents.md", "security.md"]
+        }, indent=2))
+    else:
+        print(f"Initialized Agent OS in {agents_dir}")
+        print("  - agents.md: Agent instructions (OpenAI/Anthropic standard)")
+        print("  - security.md: Kernel policies (Agent OS extension)")
+        print(f"  - Template: {policy_template}")
+        print()
+        print("Next steps:")
+        print("  1. Edit .agents/agents.md with your agent's capabilities")
+        print("  2. Customize .agents/security.md policies")
+        print("  3. Run: agentos secure --verify")
+
+    return 0

agent_os/cli/cmd_policy.py

@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""``agentos policy`` command dispatcher."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def cmd_policy(args: argparse.Namespace) -> int:
+    """Dispatch 'agentos policy <subcommand>' to the policies CLI.
+
+    Routes ``agentos policy validate <file>`` and related subcommands
+    to :mod:`agent_os.policies.cli`, which provides full JSON-Schema
+    validation and Pydantic model validation in a single pass.
+
+    Args:
+        args: Parsed CLI arguments. Expects ``args.policy_command`` and
+            any subcommand-specific attributes set by the policy subparser.
+
+    Returns:
+        Exit code from the delegated command (0 = success, 1 = failure,
+        2 = runtime error).
+    """
+    from agent_os.policies import cli as policies_cli  # type: ignore[import]
+
+    sub = getattr(args, "policy_command", None)
+    if sub == "validate":
+        return policies_cli.cmd_validate(args)
+    if sub == "test":
+        return policies_cli.cmd_test(args)
+    if sub == "diff":
+        return policies_cli.cmd_diff(args)
+
+    # No subcommand given — print help
+    print("Usage: agentos policy <validate|test|diff>")
+    print()
+    print("  validate <file>                  Validate a policy YAML/JSON file")
+    print("  test <policy> <scenarios>         Run scenario tests against a policy")
+    print("  diff <file1> <file2>             Show differences between two policies")
+    return 0

agent_os/cli/cmd_policy_gen.py

@@ -0,0 +1,180 @@
+"""Policy generator CLI — generates YAML policy files from templates.
+
+Reduces the OPA/Rego learning curve by providing ready-made policy
+templates that work out of the box with AGT's PolicyEvaluator.
+
+Usage:
+    agent-os policy generate --template strict
+    agent-os policy generate --template permissive -o my-policy.yaml
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+import yaml
+
+TEMPLATES: dict[str, dict[str, Any]] = {
+    "strict": {
+        "version": "1.0",
+        "rules": [
+            {"action": "web_search", "effect": "allow"},
+            {"action": "read_file", "effect": "allow"},
+            {
+                "action": "*",
+                "effect": "deny",
+                "reason": "Strict mode: all actions blocked by default",
+            },
+        ],
+        "content_filters": {
+            "blocked_patterns": [
+                r"\b\d{3}-\d{2}-\d{4}\b",   # SSN
+                r"\b\d{16}\b",               # Credit card
+            ],
+        },
+        "settings": {
+            "require_human_approval": True,
+            "max_tool_calls_per_session": 20,
+            "log_level": "audit",
+        },
+    },
+    "permissive": {
+        "version": "1.0",
+        "rules": [
+            {
+                "action": "*",
+                "effect": "allow",
+                "reason": "Permissive mode: all actions allowed (dev/test only)",
+            },
+        ],
+        "content_filters": {
+            "blocked_patterns": [
+                r"\b\d{3}-\d{2}-\d{4}\b",   # SSN
+                r"\b\d{16}\b",               # Credit card
+            ],
+        },
+        "settings": {
+            "require_human_approval": False,
+            "max_tool_calls_per_session": 100,
+            "log_level": "info",
+        },
+    },
+    "web-only": {
+        "version": "1.0",
+        "rules": [
+            {"action": "web_search", "effect": "allow"},
+            {"action": "web_browse", "effect": "allow"},
+            {
+                "action": "*",
+                "effect": "deny",
+                "reason": "Web-only mode: only web actions allowed",
+            },
+        ],
+        "content_filters": {
+            "blocked_patterns": [
+                r"\b\d{3}-\d{2}-\d{4}\b",
+                r"\b\d{16}\b",
+            ],
+        },
+        "settings": {
+            "require_human_approval": False,
+            "max_tool_calls_per_session": 50,
+            "log_level": "info",
+        },
+    },
+    "read-only": {
+        "version": "1.0",
+        "rules": [
+            {"action": "read_file", "effect": "allow"},
+            {"action": "list_directory", "effect": "allow"},
+            {"action": "web_search", "effect": "allow"},
+            {
+                "action": "*",
+                "effect": "deny",
+                "reason": "Read-only mode: no write or execute actions",
+            },
+        ],
+        "content_filters": {
+            "blocked_patterns": [
+                r"\b\d{3}-\d{2}-\d{4}\b",
+                r"\b\d{16}\b",
+            ],
+        },
+        "settings": {
+            "require_human_approval": False,
+            "max_tool_calls_per_session": 50,
+            "log_level": "info",
+        },
+    },
+    "custom": {
+        "version": "1.0",
+        "rules": [
+            {"action": "REPLACE_ME", "effect": "allow"},
+            {
+                "action": "*",
+                "effect": "deny",
+                "reason": "Custom template: edit rules to match your needs",
+            },
+        ],
+        "content_filters": {"blocked_patterns": []},
+        "settings": {
+            "require_human_approval": False,
+            "max_tool_calls_per_session": 50,
+            "log_level": "info",
+        },
+    },
+}
+
+TEMPLATE_CHOICES = list(TEMPLATES.keys())
+
+
+def generate_policy(template_name: str) -> str:
+    """Generate a YAML policy string from a named template."""
+    if template_name not in TEMPLATES:
+        raise ValueError(
+            f"Unknown template '{template_name}'. "
+            f"Choose from: {', '.join(TEMPLATE_CHOICES)}"
+        )
+
+    header = (
+        f"# AGT Policy — {template_name} template\n"
+        f"# Generated by: agent-os policy generate --template {template_name}\n"
+    )
+    body = yaml.dump(TEMPLATES[template_name], default_flow_style=False, sort_keys=False)
+    return header + body
+
+
+def cmd_policy_gen(argv: list[str] | None = None) -> None:
+    """CLI entry point for policy generation."""
+    parser = argparse.ArgumentParser(
+        prog="agent-os policy generate",
+        description="Generate YAML governance policies from templates.",
+    )
+    parser.add_argument(
+        "--template",
+        choices=TEMPLATE_CHOICES,
+        default="strict",
+        help="Policy template to use (default: strict)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Output file path. Defaults to stdout.",
+    )
+    args = parser.parse_args(argv)
+
+    policy_yaml = generate_policy(args.template)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(policy_yaml)
+        print(f"✅ Policy written to {args.output}", file=sys.stderr)
+    else:
+        print(policy_yaml)
+
+
+if __name__ == "__main__":
+    cmd_policy_gen()