agsec 0.1.0__tar.gz

agsec-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: agsec
+Version: 0.1.0
+Summary: AI Agent Action Firewall core SDK
+Home-page: https://github.com/yourusername/agsec
+Author: Riyandhiman
+Author-email: Riyandhiman <noreply@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/agsec
+Project-URL: Repository, https://github.com/yourusername/agsec
+Project-URL: Documentation, https://github.com/yourusername/agsec#readme
+Keywords: agent,security,policy,sandbox
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# agsec
+
+[![PyPI version](https://badge.fury.io/py/agsec.svg)](https://pypi.org/project/agsec/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+AI Agent Action Firewall - A minimal, control layer for agent actions.
+
+## Overview
+
+`agsec` provides a simple yet powerful way to add safety controls to AI agents. It acts as a "firewall" between agents and real-world actions, allowing you to define policies that approve, block, or review actions before execution.
+
+### Why agsec?
+
+- **Agent-neutral**: Works with any agent framework (LangChain, custom, etc.)
+- **Declarative policies**: Define rules in YAML or code
+- **Extensible**: Plugin system for custom actions and policies
+- **Production-ready**: Lightweight, fast, and secure
+
+## Features
+
+- ✅ **Action Registry**: Register and manage agent actions
+- ✅ **Policy Engine**: Flexible rule-based decision making
+- ✅ **YAML Policies**: Human-readable policy definitions
+- ✅ **Context Awareness**: Rules can access parameters and context
+- ✅ **Priority & Matching**: Advanced rule evaluation (priority, all/any matching)
+- ✅ **Audit Logging**: Built-in logging for all decisions
+- ✅ **Python Package**: Easy installation via PyPI
+
+## Installation
+
+### Runtime (for users)
+
+```bash
+pip install agsec
+```
+
+### Development (for contributors)
+
+```bash
+git clone https://github.com/yourusername/agsec.git
+cd agsec
+pip install -e .[dev]
+pre-commit install
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from agsec import ControlLayer
+
+# Create control layer
+control = ControlLayer()
+
+# Register an action
+@control.register_action("send_email")
+def send_email(to, subject, body):
+    return {"sent_to": to, "status": "success"}
+
+# Execute with default allow policy
+result = control.execute("send_email", {"to": "user@example.com", "subject": "Hello", "body": "Hi!"})
+print(result.result)  # {"sent_to": "user@example.com", "status": "success"}
+```
+
+### With YAML Policies
+
+```python
+from agsec import ControlLayer
+
+policy_yaml = """
+rules:
+  - action: payment
+    status: block
+    reason: "High-value payment blocked"
+    conditions:
+      amount:
+        op: ">"
+        value: 10000
+"""
+
+control = ControlLayer(policy_yaml=policy_yaml)
+
+@control.register_action("payment")
+def payment(amount):
+    return {"charged": amount}
+
+try:
+    control.execute("payment", {"amount": 15000})
+except Exception as e:
+    print(e)  # PolicyViolationError: High-value payment blocked
+```
+
+## API Reference
+
+### ControlLayer
+
+Main class for managing agent actions and policies.
+
+```python
+ControlLayer(
+    policy_engine=None,      # PolicyEngine instance
+    action_registry=None,    # ActionRegistry instance
+    logger=None,             # Custom logger
+    policy_yaml=None,        # YAML policy string
+    policy_yaml_path=None    # Path to YAML policy file
+)
+```
+
+#### Methods
+
+- `register_action(name)`: Decorator to register an action function
+- `execute(action, params, context=None)`: Execute an action with policy check
+
+### PolicyEngine
+
+Handles policy evaluation.
+
+#### Methods
+
+- `add_rule(rule)`: Add a programmatic rule function
+- `load_rules_from_yaml(yaml_text)`: Load rules from YAML string
+- `load_rules_from_yaml_file(path)`: Load rules from YAML file
+- `evaluate(action, params, context=None)`: Evaluate policy for action
+
+### Policy Status
+
+- `PolicyStatus.ALLOW`: Allow action execution
+- `PolicyStatus.BLOCK`: Block action execution
+- `PolicyStatus.REVIEW`: Mark for manual review
+
+### YAML Policy Schema
+
+```yaml
+rules:
+  - action: "action_name"          # Action to match (* for all)
+    status: "allow|block|review"   # Decision
+    reason: "Optional reason"      # Human-readable explanation
+    priority: 0                    # Higher = evaluated first
+    match: "all|any"               # Condition matching mode
+    conditions:                    # Parameter/context checks
+      param_name:
+        op: "==|!=|>|<|>=|<=|in|not_in"
+        value: "expected_value"
+      context.user_role:
+        op: "=="
+        value: "admin"
+```
+
+## Development
+
+### Setup
+
+```bash
+pip install -e .[dev]
+pre-commit install
+```
+
+### Testing
+
+```bash
+pytest
+```
+
+### Building
+
+```bash
+python -m build
+```
+
+### Releasing
+
+```bash
+./release.sh  # Requires PYPI_API_TOKEN env var
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run `pre-commit run --all-files`
+6. Submit a pull request
+
+### Code Style
+
+- Black for formatting
+- isort for import sorting
+- flake8 for linting
+- pytest for testing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Roadmap
+
+- [ ] Web dashboard for policy management
+- [ ] Advanced risk scoring
+- [ ] Multi-agent coordination
+- [ ] Enterprise integrations
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/riyandhiman14/agsec/issues)
+- Discussions: [GitHub Discussions](https://github.com/riyandhiman14/agsec/discussions)
+

agsec-0.1.0/README.md

@@ -0,0 +1,208 @@
+# agsec
+
+[![PyPI version](https://badge.fury.io/py/agsec.svg)](https://pypi.org/project/agsec/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+AI Agent Action Firewall - A minimal, control layer for agent actions.
+
+## Overview
+
+`agsec` provides a simple yet powerful way to add safety controls to AI agents. It acts as a "firewall" between agents and real-world actions, allowing you to define policies that approve, block, or review actions before execution.
+
+### Why agsec?
+
+- **Agent-neutral**: Works with any agent framework (LangChain, custom, etc.)
+- **Declarative policies**: Define rules in YAML or code
+- **Extensible**: Plugin system for custom actions and policies
+- **Production-ready**: Lightweight, fast, and secure
+
+## Features
+
+- ✅ **Action Registry**: Register and manage agent actions
+- ✅ **Policy Engine**: Flexible rule-based decision making
+- ✅ **YAML Policies**: Human-readable policy definitions
+- ✅ **Context Awareness**: Rules can access parameters and context
+- ✅ **Priority & Matching**: Advanced rule evaluation (priority, all/any matching)
+- ✅ **Audit Logging**: Built-in logging for all decisions
+- ✅ **Python Package**: Easy installation via PyPI
+
+## Installation
+
+### Runtime (for users)
+
+```bash
+pip install agsec
+```
+
+### Development (for contributors)
+
+```bash
+git clone https://github.com/yourusername/agsec.git
+cd agsec
+pip install -e .[dev]
+pre-commit install
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from agsec import ControlLayer
+
+# Create control layer
+control = ControlLayer()
+
+# Register an action
+@control.register_action("send_email")
+def send_email(to, subject, body):
+    return {"sent_to": to, "status": "success"}
+
+# Execute with default allow policy
+result = control.execute("send_email", {"to": "user@example.com", "subject": "Hello", "body": "Hi!"})
+print(result.result)  # {"sent_to": "user@example.com", "status": "success"}
+```
+
+### With YAML Policies
+
+```python
+from agsec import ControlLayer
+
+policy_yaml = """
+rules:
+  - action: payment
+    status: block
+    reason: "High-value payment blocked"
+    conditions:
+      amount:
+        op: ">"
+        value: 10000
+"""
+
+control = ControlLayer(policy_yaml=policy_yaml)
+
+@control.register_action("payment")
+def payment(amount):
+    return {"charged": amount}
+
+try:
+    control.execute("payment", {"amount": 15000})
+except Exception as e:
+    print(e)  # PolicyViolationError: High-value payment blocked
+```
+
+## API Reference
+
+### ControlLayer
+
+Main class for managing agent actions and policies.
+
+```python
+ControlLayer(
+    policy_engine=None,      # PolicyEngine instance
+    action_registry=None,    # ActionRegistry instance
+    logger=None,             # Custom logger
+    policy_yaml=None,        # YAML policy string
+    policy_yaml_path=None    # Path to YAML policy file
+)
+```
+
+#### Methods
+
+- `register_action(name)`: Decorator to register an action function
+- `execute(action, params, context=None)`: Execute an action with policy check
+
+### PolicyEngine
+
+Handles policy evaluation.
+
+#### Methods
+
+- `add_rule(rule)`: Add a programmatic rule function
+- `load_rules_from_yaml(yaml_text)`: Load rules from YAML string
+- `load_rules_from_yaml_file(path)`: Load rules from YAML file
+- `evaluate(action, params, context=None)`: Evaluate policy for action
+
+### Policy Status
+
+- `PolicyStatus.ALLOW`: Allow action execution
+- `PolicyStatus.BLOCK`: Block action execution
+- `PolicyStatus.REVIEW`: Mark for manual review
+
+### YAML Policy Schema
+
+```yaml
+rules:
+  - action: "action_name"          # Action to match (* for all)
+    status: "allow|block|review"   # Decision
+    reason: "Optional reason"      # Human-readable explanation
+    priority: 0                    # Higher = evaluated first
+    match: "all|any"               # Condition matching mode
+    conditions:                    # Parameter/context checks
+      param_name:
+        op: "==|!=|>|<|>=|<=|in|not_in"
+        value: "expected_value"
+      context.user_role:
+        op: "=="
+        value: "admin"
+```
+
+## Development
+
+### Setup
+
+```bash
+pip install -e .[dev]
+pre-commit install
+```
+
+### Testing
+
+```bash
+pytest
+```
+
+### Building
+
+```bash
+python -m build
+```
+
+### Releasing
+
+```bash
+./release.sh  # Requires PYPI_API_TOKEN env var
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run `pre-commit run --all-files`
+6. Submit a pull request
+
+### Code Style
+
+- Black for formatting
+- isort for import sorting
+- flake8 for linting
+- pytest for testing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Roadmap
+
+- [ ] Web dashboard for policy management
+- [ ] Advanced risk scoring
+- [ ] Multi-agent coordination
+- [ ] Enterprise integrations
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/riyandhiman14/agsec/issues)
+- Discussions: [GitHub Discussions](https://github.com/riyandhiman14/agsec/discussions)
+

agsec-0.1.0/agsec/__init__.py

@@ -0,0 +1,12 @@
+from .control import ControlLayer
+from .policy import PolicyEngine
+from .registry import ActionRegistry
+from .types import PolicyResult, PolicyStatus
+
+__all__ = [
+    "ControlLayer",
+    "PolicyEngine",
+    "PolicyResult",
+    "PolicyStatus",
+    "ActionRegistry",
+]

agsec-0.1.0/agsec/control.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from .exceptions import ActionNotFoundError, PolicyViolationError
+from .policy import PolicyEngine
+from .registry import ActionRegistry
+from .types import ActionExecutionResult, PolicyResult, PolicyStatus
+
+
+class ControlLayer:
+    def __init__(
+        self,
+        policy_engine: Optional[PolicyEngine] = None,
+        action_registry: Optional[ActionRegistry] = None,
+        logger: Optional[logging.Logger] = None,
+        policy_yaml: Optional[str] = None,
+        policy_yaml_path: Optional[str] = None,
+    ):
+        self.policy_engine = policy_engine or PolicyEngine()
+        if policy_yaml is not None:
+            self.policy_engine.load_rules_from_yaml(policy_yaml)
+        elif policy_yaml_path is not None:
+            self.policy_engine.load_rules_from_yaml_file(policy_yaml_path)
+
+        self.action_registry = action_registry or ActionRegistry()
+        self.logger = logger or logging.getLogger("agsec")
+        self.logger.setLevel(logging.DEBUG)
+
+    def register_action(self, name: str):
+        def decorator(func):
+            self.action_registry.register(name, func)
+            return func
+
+        return decorator
+
+    def execute(self, action: str, params: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> ActionExecutionResult:
+        context = context or {}
+
+        policy: PolicyResult = self.policy_engine.evaluate(action, params, context)
+        self.logger.info(f"policy evaluation for action=%s -> %s", action, policy)
+
+        if policy.status == PolicyStatus.BLOCK:
+            self.logger.warning("Blocked action: %s, reason=%s", action, policy.reason)
+            raise PolicyViolationError(policy.reason)
+
+        if policy.status == PolicyStatus.REVIEW:
+            self.logger.info("Action requires manual review: %s, reason=%s", action, policy.reason)
+            return ActionExecutionResult(action=action, params=params, result=None, policy=policy)
+
+        if policy.status != PolicyStatus.ALLOW:
+            raise PolicyViolationError(f"Unexpected policy status: {policy.status}")
+
+        try:
+            act = self.action_registry.get(action)
+        except ActionNotFoundError as exc:
+            self.logger.error("Action not found: %s", action)
+            raise
+
+        result = act(**params)
+        exec_result = ActionExecutionResult(action=action, params=params, result=result, policy=policy)
+
+        self.logger.info("Executed action: %s, result=%s", action, result)
+        return exec_result

agsec-0.1.0/agsec/exceptions.py

@@ -0,0 +1,6 @@
+class ActionNotFoundError(Exception):
+    pass
+
+
+class PolicyViolationError(Exception):
+    pass

agsec-0.1.0/agsec/policy.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, Dict, List, Optional
+
+import yaml
+
+from .exceptions import PolicyViolationError
+from .types import PolicyResult, PolicyStatus
+
+PolicyRule = Callable[[str, Dict[str, Any], Optional[Dict[str, Any]]], Optional[PolicyResult]]
+
+
+def _evaluate_condition(value: Any, condition: Any) -> bool:
+    if isinstance(condition, dict):
+        op = condition.get("op")
+        expected = condition.get("value")
+
+        if op is None or expected is None:
+            raise ValueError("Condition must have 'op' and 'value'")
+
+        if op == "==":
+            return value == expected
+        if op == "!=":
+            return value != expected
+        if op == ">":
+            return value > expected
+        if op == "<":
+            return value < expected
+        if op == ">=":
+            return value >= expected
+        if op == "<=":
+            return value <= expected
+        if op == "in":
+            return value in expected
+        if op == "not_in":
+            return value not in expected
+        raise ValueError(f"Unsupported condition operator: {op}")
+
+    # Scalar condition is treated as equals.
+    return value == condition
+
+
+def _resolve_condition_value(key: str, params: Dict[str, Any], context: Optional[Dict[str, Any]]) -> Any:
+    if key.startswith("params."):
+        return params.get(key.split(".", 1)[1])
+    if key.startswith("context."):
+        if context is None:
+            return None
+        return context.get(key.split(".", 1)[1])
+
+    if key in params:
+        return params[key]
+    if context and key in context:
+        return context[key]
+    return None
+
+
+def _build_rule_from_definition(definition: Dict[str, Any]) -> PolicyRule:
+    action_name = definition.get("action")
+    status = definition.get("status")
+    reason = definition.get("reason", "")
+    conditions = definition.get("conditions", {})
+    match_type = definition.get("match", "all")
+    priority = int(definition.get("priority", 0))
+
+    if action_name is None or status is None:
+        raise ValueError("Each policy rule must include 'action' and 'status'")
+
+    status_enum = PolicyStatus(status)
+
+    def rule(action: str, params: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> Optional[PolicyResult]:
+        if action_name != "*" and action != action_name:
+            return None
+
+        if conditions:
+            hits = []
+            for key, cond in conditions.items():
+                value = _resolve_condition_value(key, params, context)
+                if value is None:
+                    hits.append(False)
+                    continue
+
+                result = _evaluate_condition(value, cond)
+                hits.append(bool(result))
+
+            if match_type == "all" and not all(hits):
+                return None
+            if match_type == "any" and not any(hits):
+                return None
+
+        return PolicyResult(status=status_enum, reason=reason)
+
+    setattr(rule, "priority", priority)
+    return rule
+
+
+class PolicyEngine:
+    def __init__(self, rules: Optional[List[PolicyRule]] = None):
+        self.rules = rules or []
+        self._sort_rules()
+
+    def add_rule(self, rule: PolicyRule) -> None:
+        if not hasattr(rule, "priority"):
+            setattr(rule, "priority", 0)
+        self.rules.append(rule)
+        self._sort_rules()
+
+    def _sort_rules(self) -> None:
+        self.rules.sort(key=lambda r: getattr(r, "priority", 0), reverse=True)
+
+    def load_rules_from_yaml(self, yaml_text: str) -> None:
+        parsed = yaml.safe_load(yaml_text)
+        if not isinstance(parsed, dict):
+            raise ValueError("YAML policy must contain a top-level mapping with 'rules'")
+
+        rules = parsed.get("rules")
+        if not isinstance(rules, list):
+            raise ValueError("'rules' must be a list")
+
+        for rule_def in rules:
+            if not isinstance(rule_def, dict):
+                raise ValueError("Each rule must be a mapping")
+            self.add_rule(_build_rule_from_definition(rule_def))
+
+    def load_rules_from_yaml_file(self, path: str) -> None:
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"YAML policy file not found: {path}")
+
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
+        self.load_rules_from_yaml(text)
+
+    def evaluate(self, action: str, params: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> PolicyResult:
+        context = context or {}
+
+        for rule in self.rules:
+            decision = rule(action, params, context)
+            if decision is not None:
+                if not isinstance(decision, PolicyResult):
+                    raise PolicyViolationError(f"Policy rule returned invalid type: {type(decision)}")
+                return decision
+
+        return PolicyResult(status=PolicyStatus.ALLOW, reason="default allow")

agsec-0.1.0/agsec/registry.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict
+
+from .exceptions import ActionNotFoundError
+
+ActionFunc = Callable[..., Any]
+
+
+class ActionRegistry:
+    def __init__(self):
+        self._actions: Dict[str, ActionFunc] = {}
+
+    def register(self, name: str, func: ActionFunc) -> ActionFunc:
+        if name in self._actions:
+            raise ValueError(f"Action '{name}' is already registered")
+        self._actions[name] = func
+        return func
+
+    def get(self, name: str) -> ActionFunc:
+        if name not in self._actions:
+            raise ActionNotFoundError(f"Action '{name}' not registered")
+        return self._actions[name]
+
+    def list_actions(self) -> Dict[str, ActionFunc]:
+        return dict(self._actions)

agsec-0.1.0/agsec/types.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class PolicyStatus(str, Enum):
+    ALLOW = "allow"
+    BLOCK = "block"
+    REVIEW = "review"
+
+
+@dataclass
+class PolicyResult:
+    status: PolicyStatus
+    reason: str = ""
+    metadata: Dict[str, Any] = None
+
+
+@dataclass
+class ActionExecutionResult:
+    action: str
+    params: Dict[str, Any]
+    result: Any
+    policy: PolicyResult

agsec-0.1.0/agsec.egg-info/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: agsec
+Version: 0.1.0
+Summary: AI Agent Action Firewall core SDK
+Home-page: https://github.com/yourusername/agsec
+Author: Riyandhiman
+Author-email: Riyandhiman <noreply@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/agsec
+Project-URL: Repository, https://github.com/yourusername/agsec
+Project-URL: Documentation, https://github.com/yourusername/agsec#readme
+Keywords: agent,security,policy,sandbox
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# agsec
+
+[![PyPI version](https://badge.fury.io/py/agsec.svg)](https://pypi.org/project/agsec/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+AI Agent Action Firewall - A minimal, control layer for agent actions.
+
+## Overview
+
+`agsec` provides a simple yet powerful way to add safety controls to AI agents. It acts as a "firewall" between agents and real-world actions, allowing you to define policies that approve, block, or review actions before execution.
+
+### Why agsec?
+
+- **Agent-neutral**: Works with any agent framework (LangChain, custom, etc.)
+- **Declarative policies**: Define rules in YAML or code
+- **Extensible**: Plugin system for custom actions and policies
+- **Production-ready**: Lightweight, fast, and secure
+
+## Features
+
+- ✅ **Action Registry**: Register and manage agent actions
+- ✅ **Policy Engine**: Flexible rule-based decision making
+- ✅ **YAML Policies**: Human-readable policy definitions
+- ✅ **Context Awareness**: Rules can access parameters and context
+- ✅ **Priority & Matching**: Advanced rule evaluation (priority, all/any matching)
+- ✅ **Audit Logging**: Built-in logging for all decisions
+- ✅ **Python Package**: Easy installation via PyPI
+
+## Installation
+
+### Runtime (for users)
+
+```bash
+pip install agsec
+```
+
+### Development (for contributors)
+
+```bash
+git clone https://github.com/yourusername/agsec.git
+cd agsec
+pip install -e .[dev]
+pre-commit install
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from agsec import ControlLayer
+
+# Create control layer
+control = ControlLayer()
+
+# Register an action
+@control.register_action("send_email")
+def send_email(to, subject, body):
+    return {"sent_to": to, "status": "success"}
+
+# Execute with default allow policy
+result = control.execute("send_email", {"to": "user@example.com", "subject": "Hello", "body": "Hi!"})
+print(result.result)  # {"sent_to": "user@example.com", "status": "success"}
+```
+
+### With YAML Policies
+
+```python
+from agsec import ControlLayer
+
+policy_yaml = """
+rules:
+  - action: payment
+    status: block
+    reason: "High-value payment blocked"
+    conditions:
+      amount:
+        op: ">"
+        value: 10000
+"""
+
+control = ControlLayer(policy_yaml=policy_yaml)
+
+@control.register_action("payment")
+def payment(amount):
+    return {"charged": amount}
+
+try:
+    control.execute("payment", {"amount": 15000})
+except Exception as e:
+    print(e)  # PolicyViolationError: High-value payment blocked
+```
+
+## API Reference
+
+### ControlLayer
+
+Main class for managing agent actions and policies.
+
+```python
+ControlLayer(
+    policy_engine=None,      # PolicyEngine instance
+    action_registry=None,    # ActionRegistry instance
+    logger=None,             # Custom logger
+    policy_yaml=None,        # YAML policy string
+    policy_yaml_path=None    # Path to YAML policy file
+)
+```
+
+#### Methods
+
+- `register_action(name)`: Decorator to register an action function
+- `execute(action, params, context=None)`: Execute an action with policy check
+
+### PolicyEngine
+
+Handles policy evaluation.
+
+#### Methods
+
+- `add_rule(rule)`: Add a programmatic rule function
+- `load_rules_from_yaml(yaml_text)`: Load rules from YAML string
+- `load_rules_from_yaml_file(path)`: Load rules from YAML file
+- `evaluate(action, params, context=None)`: Evaluate policy for action
+
+### Policy Status
+
+- `PolicyStatus.ALLOW`: Allow action execution
+- `PolicyStatus.BLOCK`: Block action execution
+- `PolicyStatus.REVIEW`: Mark for manual review
+
+### YAML Policy Schema
+
+```yaml
+rules:
+  - action: "action_name"          # Action to match (* for all)
+    status: "allow|block|review"   # Decision
+    reason: "Optional reason"      # Human-readable explanation
+    priority: 0                    # Higher = evaluated first
+    match: "all|any"               # Condition matching mode
+    conditions:                    # Parameter/context checks
+      param_name:
+        op: "==|!=|>|<|>=|<=|in|not_in"
+        value: "expected_value"
+      context.user_role:
+        op: "=="
+        value: "admin"
+```
+
+## Development
+
+### Setup
+
+```bash
+pip install -e .[dev]
+pre-commit install
+```
+
+### Testing
+
+```bash
+pytest
+```
+
+### Building
+
+```bash
+python -m build
+```
+
+### Releasing
+
+```bash
+./release.sh  # Requires PYPI_API_TOKEN env var
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run `pre-commit run --all-files`
+6. Submit a pull request
+
+### Code Style
+
+- Black for formatting
+- isort for import sorting
+- flake8 for linting
+- pytest for testing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Roadmap
+
+- [ ] Web dashboard for policy management
+- [ ] Advanced risk scoring
+- [ ] Multi-agent coordination
+- [ ] Enterprise integrations
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/riyandhiman14/agsec/issues)
+- Discussions: [GitHub Discussions](https://github.com/riyandhiman14/agsec/discussions)
+

agsec-0.1.0/agsec.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+setup.py
+agsec/__init__.py
+agsec/control.py
+agsec/exceptions.py
+agsec/policy.py
+agsec/registry.py
+agsec/types.py
+agsec.egg-info/PKG-INFO
+agsec.egg-info/SOURCES.txt
+agsec.egg-info/dependency_links.txt
+agsec.egg-info/requires.txt
+agsec.egg-info/top_level.txt
+tests/__init__.py
+tests/test_control.py

agsec-0.1.0/agsec.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agsec-0.1.0/agsec.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

agsec-0.1.0/agsec.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+agsec
+tests

agsec-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agsec"
+version = "0.1.0"
+description = "AI Agent Action Firewall core SDK"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+keywords = ["agent", "security", "policy", "sandbox"]
+authors = [
+  {name = "Riyandhiman", email = "noreply@example.com"}
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "PyYAML>=6.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/yourusername/agsec"
+"Repository" = "https://github.com/yourusername/agsec"
+"Documentation" = "https://github.com/yourusername/agsec#readme"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q"
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+target-version = ['py38']
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.flake8]
+max-line-length = 88
+extend-ignore = ["E203", "W503"]

agsec-0.1.0/setup.cfg

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

agsec-0.1.0/setup.py

@@ -0,0 +1,36 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="agsec",
+    version="0.1.0",
+    author="Riyandhiman",
+    author_email="noreply@example.com",
+    description="AI Agent Action Firewall core SDK",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/yourusername/agsec",
+    packages=find_packages(),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.8",
+    install_requires=[
+        "PyYAML>=6.0",
+    ],
+    extras_require={
+        "dev": [
+            "pre-commit>=3.0",
+            "black>=24.0",
+            "isort>=5.0",
+            "flake8>=7.0",
+            "pytest>=6.0",
+            "build>=1.0",
+            "twine>=4.0",
+        ],
+    },
+)

agsec-0.1.0/tests/test_control.py

@@ -0,0 +1,190 @@
+import logging
+
+from agsec import ControlLayer, PolicyEngine, PolicyResult, PolicyStatus
+from agsec.exceptions import PolicyViolationError
+
+
+def test_control_execute_allow(monkeypatch):
+    control = ControlLayer(policy_engine=PolicyEngine())
+
+    @control.register_action("noop")
+    def noop():
+        return "ok"
+
+    result = control.execute("noop", {})
+    assert result.result == "ok"
+    assert result.policy.status == PolicyStatus.ALLOW
+
+
+def test_control_execute_block():
+    engine = PolicyEngine()
+
+    def deny_all(action, params, context):
+        return PolicyResult(status=PolicyStatus.BLOCK, reason="denied")
+
+    engine.add_rule(deny_all)
+    control = ControlLayer(policy_engine=engine)
+
+    @control.register_action("noop")
+    def noop():
+        return "ok"
+
+    try:
+        control.execute("noop", {})
+        assert False, "Expected PolicyViolationError"
+    except PolicyViolationError:
+        pass
+
+
+def test_policy_review():
+    engine = PolicyEngine()
+
+    def review_payment(action, params, context):
+        if action == "payment" and params.get("amount") > 5000:
+            return PolicyResult(status=PolicyStatus.REVIEW, reason="manual review required")
+        return None
+
+    engine.add_rule(review_payment)
+    control = ControlLayer(policy_engine=engine)
+
+    @control.register_action("payment")
+    def payment(amount):
+        return {"charged": amount}
+
+    result = control.execute("payment", {"amount": 6000})
+    assert result.result is None
+    assert result.policy.status == PolicyStatus.REVIEW
+
+
+def test_policy_engine_load_yaml_block():
+    yaml_rules = """
+rules:
+  - action: payment
+    status: block
+    reason: "Amount over limit"
+    conditions:
+      amount:
+        op: ">"
+        value: 10000
+"""
+
+    engine = PolicyEngine()
+    engine.load_rules_from_yaml(yaml_rules)
+
+    control = ControlLayer(policy_engine=engine)
+
+    @control.register_action("payment")
+    def payment(amount):
+        return {"charged": amount}
+
+    try:
+        control.execute("payment", {"amount": 15000})
+        assert False, "Expected PolicyViolationError"
+    except PolicyViolationError as e:
+        assert "Amount over limit" in str(e)
+
+
+def test_control_layer_load_policy_yaml_direct():
+    yaml_rules = """
+rules:
+  - action: send_email
+    status: allow
+    reason: "always allow"
+"""
+
+    control = ControlLayer(policy_yaml=yaml_rules)
+
+    @control.register_action("send_email")
+    def send_email(to):
+        return {"sent_to": to}
+
+    result = control.execute("send_email", {"to": "x@example.com"})
+    assert result.result == {"sent_to": "x@example.com"}
+    assert result.policy.status == PolicyStatus.ALLOW
+
+
+def test_policy_engine_yaml_priority():
+    yaml_rules = """
+rules:
+  - action: payment
+    status: allow
+    priority: 0
+  - action: payment
+    status: block
+    reason: "Higher priority block"
+    priority: 100
+"""
+
+    engine = PolicyEngine()
+    engine.load_rules_from_yaml(yaml_rules)
+
+    control = ControlLayer(policy_engine=engine)
+
+    @control.register_action("payment")
+    def payment(amount):
+        return {"charged": amount}
+
+    try:
+        control.execute("payment", {"amount": 10})
+        assert False, "Expected PolicyViolationError due to higher priority block"
+    except PolicyViolationError as e:
+        assert "Higher priority block" in str(e)
+
+
+def test_policy_engine_yaml_match_any():
+    yaml_rules = """
+rules:
+  - action: data_export
+    status: block
+    match: any
+    conditions:
+      table:
+        op: "=="
+        value: "sensitive"
+      export_type:
+        op: "=="
+        value: "external"
+"""
+
+    engine = PolicyEngine()
+    engine.load_rules_from_yaml(yaml_rules)
+
+    control = ControlLayer(policy_engine=engine)
+
+    @control.register_action("data_export")
+    def data_export(table, export_type):
+        return {"ok": True}
+
+    # should block on table match
+    try:
+        control.execute("data_export", {"table": "sensitive", "export_type": "internal"})
+        assert False
+    except PolicyViolationError:
+        pass
+
+
+def test_policy_engine_yaml_context_condition():
+    yaml_rules = """
+rules:
+  - action: password_reset
+    status: block
+    conditions:
+      context.user_role:
+        op: "=="
+        value: "guest"
+"""
+
+    engine = PolicyEngine()
+    engine.load_rules_from_yaml(yaml_rules)
+
+    control = ControlLayer(policy_engine=engine)
+
+    @control.register_action("password_reset")
+    def password_reset(user_id):
+        return {"reset": user_id}
+
+    try:
+        control.execute("password_reset", {"user_id": "u1"}, context={"user_role": "guest"})
+        assert False
+    except PolicyViolationError:
+        pass