awwall 0.1.0__py3-none-any.whl

awwall/__init__.py

@@ -0,0 +1,121 @@
+"""awwall: egress allowlist that fails closed."""
+
+import re
+from typing import NamedTuple, Optional
+
+
+class AllowRule(NamedTuple):
+    pattern: str
+    rule_type: str
+    description: str = ""
+
+class Policy:
+    def __init__(self, rules: Optional[list] = None):
+        self.rules = rules or []
+
+    @classmethod
+    def from_dict(cls, data):
+        if not isinstance(data, dict):
+            raise ValueError("Policy must be a dictionary")
+        rules_data = data.get("rules", [])
+        if not isinstance(rules_data, list):
+            raise ValueError("rules must be a list")
+        rules = []
+        for rule_dict in rules_data:
+            if not isinstance(rule_dict, dict):
+                raise ValueError("Each rule must be a dictionary")
+            pattern = rule_dict.get("pattern")
+            rule_type = rule_dict.get("rule_type")
+            description = rule_dict.get("description", "")
+            if not pattern or not rule_type:
+                raise ValueError("Each rule must have pattern and rule_type")
+            if rule_type not in ("exact", "domain", "glob"):
+                raise ValueError(f"Invalid rule_type: {rule_type}")
+            rules.append(AllowRule(pattern, rule_type, description))
+        return cls(rules)
+
+    def check(self, host):
+        host = host.strip().lower()
+        for rule in self.rules:
+            if self._rule_matches(host, rule):
+                return True, rule
+        return False, None
+
+    def _rule_matches(self, host, rule):
+        pattern = rule.pattern.lower()
+        if rule.rule_type == "exact":
+            return host == pattern
+        elif rule.rule_type == "domain":
+            if host == pattern:
+                return True
+            if host.endswith("." + pattern):
+                return True
+            return False
+        elif rule.rule_type == "glob":
+            regex = re.escape(pattern).replace(r"\*", ".*")
+            return bool(re.fullmatch(regex, host))
+        return False
+
+    def to_dict(self):
+        return {
+            "rules": [
+                {
+                    "pattern": rule.pattern,
+                    "rule_type": rule.rule_type,
+                    "description": rule.description
+                }
+                for rule in self.rules
+            ]
+        }
+
+    def to_hosts_format(self):
+        lines = [
+            "# Generated by awwall - egress allowlist",
+            "# NOTE: This only represents the rules in awwall format.",
+            "# Use 'awwall emit --format iptables' for actual firewall rules.",
+        ]
+
+        for rule in self.rules:
+            if rule.rule_type in ("exact", "domain"):
+                comment = f" # {rule.description}" if rule.description else ""
+                lines.append(f"127.0.0.1 {rule.pattern}{comment}")
+
+        return "\n".join(lines) + "\n"
+
+    def to_iptables_format(self):
+        lines = [
+            "#!/bin/bash",
+            "# Generated by awwall - egress allowlist",
+            "# NOTE: These rules require integration with DNS resolution.",
+            "# Recommended: use this with conntrack + DNS interception.",
+            "",
+            "# Default: DROP outbound",
+            "iptables -P OUTPUT DROP",
+            "iptables -P FORWARD DROP",
+            "",
+            "# Allow localhost",
+            "iptables -A OUTPUT -d 127.0.0.1 -j ACCEPT",
+            "iptables -A OUTPUT -d ::1 -j ACCEPT",
+            "",
+            "# Allow related/established",
+            "iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT",
+            "",
+            "# Rules (requires DNS A/AAAA record resolution)",
+        ]
+
+        for rule in self.rules:
+            comment = f" # {rule.description}" if rule.description else ""
+            if rule.rule_type == "exact":
+                lines.append(f"# EXACT: {rule.pattern}{comment}")
+                lines.append(f"# iptables -A OUTPUT -d <IP-of-{rule.pattern}> -j ACCEPT")
+            elif rule.rule_type == "domain":
+                lines.append(f"# DOMAIN: {rule.pattern}{comment}")
+                lines.append(f"# iptables -A OUTPUT -d <IP-of-*.{rule.pattern}> -j ACCEPT")
+            elif rule.rule_type == "glob":
+                lines.append(f"# GLOB: {rule.pattern}{comment}")
+                lines.append(f"# iptables -A OUTPUT -d <IP-matching-{rule.pattern}> -j ACCEPT")
+
+        return "\n".join(lines) + "\n"
+
+__all__ = ["Policy", "AllowRule"]
+

awwall/_doctor.py

@@ -0,0 +1,145 @@
+"""Stack-aware `doctor` for awwall.
+
+GENERATED BY gen_aw_doctor.py -- DO NOT EDIT.
+Regenerate it with the generator named above; a hand-edit here is reverted by
+the next run and fails the parity gate.
+
+Why a doctor exists at all: the aw* bricks are designed to COMPOSE, so the
+interesting failures live BETWEEN them. "awwall is installed" is not the useful
+fact -- "awwall is installed and the thing it pairs with is not" is. This reports
+the whole stack, not just itself.
+
+stdlib only, on purpose: a diagnostic that cannot run because a dependency is
+missing is worthless precisely when you need it.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+
+#: Frozen from AitherOS/config/ecosystem.yaml at generation time. A shipped
+#: package cannot read the registry, and a doctor that guessed at the family
+#: would go stale in silence. Regenerate to update.
+SELF = 'awwall'
+FAMILY = [
+    'awask', 'awbac', 'awbrowse', 'awdit', 'awevolve', 'awfind', 'awgit',
+    'awgraph', 'awiam', 'awkno', 'awm', 'awmail', 'awnboard', 'awnest',
+    'awnet', 'awnode', 'awpredict', 'awprism', 'awreason', 'awrecover',
+    'awrecurse', 'awrelay', 'awrena', 'awrepl', 'awresearch', 'awrise',
+    'awrun', 'awseal', 'awshare', 'awtunnel',
+]
+PAIRS_WITH = ['awbac', 'awdit', 'adk', 'awiam', 'awnboard', 'awnest', 'awnet', 'awnode', 'awtunnel']
+
+#: This brick's OWN config, read out of its source at generation time.
+#: ENV_REQUIRED is `os.environ["X"]` -- absent, that is a KeyError the moment
+#: the line runs. ENV_OPTIONAL is `os.getenv("X")`, which returns None and lets
+#: the caller cope. Only this brick's namespace is listed: reporting the
+#: platform-wide vars it also touches would be noise, and a doctor that floods
+#: gets ignored.
+ENV_REQUIRED = []
+ENV_OPTIONAL = []
+
+
+def _installed(mod: str) -> "str | None":
+    """Version if importable, else None. Never raises -- a broken sibling must
+    not take the diagnostic down with it."""
+    try:
+        if importlib.util.find_spec(mod) is None:
+            return None
+    except (ImportError, ValueError):
+        return None
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version(mod)
+        except PackageNotFoundError:
+            return "installed"
+    except Exception:
+        return "installed"
+
+
+def report(out=None) -> int:
+    """Print the stack picture. 0 = this brick and its pairs are present."""
+    out = out or sys.stdout
+    print(f"{SELF} doctor", file=out)
+
+    mine = _installed(SELF)
+    print(f"  self       {SELF} {mine or 'NOT IMPORTABLE'}", file=out)
+    shim = shutil.which(SELF)
+    print(f"  command    {shim or 'not on PATH'}", file=out)
+
+    # The stack. Siblings this brick pairs with are called out separately,
+    # because a missing pair is a REASON, while a missing unrelated brick is
+    # just a fact about your machine.
+    missing_pairs, present = [], []
+    for name in FAMILY:
+        v = _installed(name)
+        if v:
+            present.append(name)
+        elif name in PAIRS_WITH:
+            missing_pairs.append(name)
+    print(f"  stack      {len(present)}/{len(FAMILY)} aw* packages installed",
+          file=out)
+    if present:
+        print(f"             {' '.join(sorted(present))}", file=out)
+
+    missing_req = [v for v in ENV_REQUIRED if not os.environ.get(v)]
+    if ENV_REQUIRED or ENV_OPTIONAL:
+        have = sum(1 for v in ENV_REQUIRED + ENV_OPTIONAL if os.environ.get(v))
+        total = len(ENV_REQUIRED) + len(ENV_OPTIONAL)
+        print(f"  config     {have}/{total} of this brick's own vars set", file=out)
+        if missing_req:
+            # Not a preference. os.environ[...] raises the moment it runs.
+            print(f"             MISSING REQUIRED: {' '.join(missing_req)}", file=out)
+
+    local = _local_checks()
+    for line in local:
+        print(f"  {line}", file=out)
+
+    if mine is None:
+        print(f"\nverdict: {SELF} itself is not importable. Reinstall it before "
+              f"anything else here means much.", file=out)
+        return 1
+    if missing_req:
+        print(f"\nverdict: {SELF} is missing required config "
+              f"({', '.join(missing_req)}). Those are read with os.environ[...], "
+              f"so the code path that needs them raises rather than degrades.",
+              file=out)
+        return 1
+    if missing_pairs:
+        print(f"\nverdict: {SELF} works, but pairs with "
+              f"{', '.join(sorted(missing_pairs))} which "
+              f"{'is' if len(missing_pairs) == 1 else 'are'} not installed. "
+              f"That is a capability you are missing, not an error.", file=out)
+        return 0
+    print(f"\nverdict: {SELF} and everything it pairs with are present.", file=out)
+    return 0
+
+
+def _local_checks() -> "list[str]":
+    """Per-brick checks, if this package defines them.
+
+    Kept as a HOOK rather than generated guesses: the generator knows the family
+    from the registry, but it does not know what awwall needs at runtime, and a
+    doctor that invented config requirements would be confidently wrong. A
+    package supplies `_doctor_local()` returning display lines; absent, the
+    stack picture above still stands on its own.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+    except Exception:
+        return []
+    try:
+        return list(mod._doctor_local())
+    except Exception as exc:                       # noqa: BLE001
+        return [f"local     checks raised {type(exc).__name__}: {exc}"]
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    return report()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

awwall/cli.py

@@ -0,0 +1,294 @@
+"""awwall CLI: check and manage egress allowlists."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from awwall import AllowRule, Policy
+
+DEFAULT_POLICY_FILE = Path.home() / ".awwall" / "policy.json"
+
+def load_policy(policy_file=None):
+    """Load policy from file or return empty policy."""
+    if policy_file is None:
+        policy_file = DEFAULT_POLICY_FILE
+
+    if isinstance(policy_file, str):
+        policy_file = Path(policy_file)
+
+    if policy_file.exists():
+        try:
+            with open(policy_file, encoding='utf-8') as f:
+                data = json.load(f)
+            return Policy.from_dict(data)
+        except Exception as e:
+            print(f"ERROR: Failed to load policy: {e}", file=sys.stderr)
+            return None
+
+    return Policy()
+
+def save_policy(policy, policy_file=None):
+    """Save policy to file."""
+    if policy_file is None:
+        policy_file = DEFAULT_POLICY_FILE
+
+    if isinstance(policy_file, str):
+        policy_file = Path(policy_file)
+
+    policy_file.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(policy_file, 'w', encoding='utf-8') as f:
+        json.dump(policy.to_dict(), f, indent=2)
+
+def cmd_allow(args):
+    """Add an allowed host to the policy."""
+    policy = load_policy(args.policy_file)
+    if policy is None:
+        return 2
+
+    # Determine rule type
+    if args.type:
+        rule_type = args.type
+    else:
+        if '*' in args.host:
+            rule_type = 'glob'
+        elif args.host.startswith('.') or '.' not in args.host:
+            rule_type = 'domain' if '.' not in args.host or args.host.startswith('.') else 'exact'
+        else:
+            rule_type = 'domain' if args.as_domain else 'exact'
+
+    new_rule = AllowRule(args.host, rule_type, args.description or "")
+
+    # Check for duplicates
+    for rule in policy.rules:
+        if rule.pattern.lower() == args.host.lower() and rule.rule_type == rule_type:
+            print(f"Rule already exists: {rule.pattern} ({rule_type})", file=sys.stderr)
+            return 1
+
+    policy.rules.append(new_rule)
+    save_policy(policy, args.policy_file)
+    print(f"Added: {args.host} ({rule_type})")
+    return 0
+
+def cmd_check(args):
+    """Check if a host is allowed."""
+    policy = load_policy(args.policy_file)
+    if policy is None:
+        return 2
+
+    allowed, rule = policy.check(args.host)
+
+    if allowed:
+        if args.verbose:
+            print(f"ALLOWED: {args.host} (matches: {rule.pattern})")
+        return 0
+    else:
+        if args.verbose:
+            print(f"DENIED: {args.host} (no rule matched)")
+        return 1
+
+def cmd_explain(args):
+    """Explain why a host was allowed or denied."""
+    policy = load_policy(args.policy_file)
+    if policy is None:
+        return 2
+
+    allowed, rule = policy.check(args.host)
+
+    if allowed:
+        print(f"ALLOWED: {args.host}")
+        print(f"  Matched rule: {rule.pattern} (type: {rule.rule_type})")
+        if rule.description:
+            print(f"  Description: {rule.description}")
+        return 0
+    else:
+        print(f"DENIED: {args.host}")
+        if policy.rules:
+            print(f"  Reason: No rule matched (checked {len(policy.rules)} rule(s))")
+        else:
+            print("  Reason: Policy is empty (default deny)")
+        return 1
+
+def cmd_emit(args):
+    """Emit policy in different formats."""
+    policy = load_policy(args.policy_file)
+    if policy is None:
+        return 2
+
+    if args.format == 'hosts':
+        output = policy.to_hosts_format()
+    elif args.format == 'iptables':
+        output = policy.to_iptables_format()
+    elif args.format == 'json':
+        output = json.dumps(policy.to_dict(), indent=2)
+    else:
+        print(f"Unknown format: {args.format}", file=sys.stderr)
+        return 1
+
+    if args.output:
+        with open(args.output, 'w', encoding='utf-8') as f:
+            f.write(output)
+        print(f"Wrote {args.format} format to {args.output}")
+        return 0
+    else:
+        print(output, end='')
+        return 0
+
+def cmd_list(args):
+    """List all rules in the policy."""
+    policy = load_policy(args.policy_file)
+    if policy is None:
+        return 2
+
+    if not policy.rules:
+        print("No rules defined (default: deny everything)")
+        return 0
+
+    print(f"Policy rules ({len(policy.rules)} total):\n")
+    for i, rule in enumerate(policy.rules, 1):
+        desc = f" - {rule.description}" if rule.description else ""
+        print(f"  {i}. {rule.pattern} [{rule.rule_type}]{desc}")
+
+    return 0
+
+def cmd_self_test(args):
+    """Run self-tests to verify the policy engine."""
+    print("Running awwall self-tests...")
+
+    # Test 1: Default deny (empty policy)
+    empty_policy = Policy()
+    allowed, _ = empty_policy.check("example.com")
+    assert not allowed, "FAIL: Empty policy should deny all hosts"
+    print("  [PASS] Empty policy denies all")
+
+    # Test 2: Exact match
+    exact_policy = Policy([AllowRule("example.com", "exact")])
+    allowed, rule = exact_policy.check("example.com")
+    assert allowed and rule.pattern == "example.com", "FAIL: Exact match failed"
+    print("  [PASS] Exact match works")
+
+    # Test 3: Exact match negative (should deny similar)
+    allowed, _ = exact_policy.check("api.example.com")
+    assert not allowed, "FAIL: Exact match should not match subdomain"
+    print("  [PASS] Exact match rejects subdomains")
+
+    # Test 4: Domain match (includes subdomains)
+    domain_policy = Policy([AllowRule("example.com", "domain")])
+    allowed, _ = domain_policy.check("api.example.com")
+    assert allowed, "FAIL: Domain match should include subdomains"
+    print("  [PASS] Domain match includes subdomains")
+
+    # Test 5: Domain doesn't match different domain
+    allowed, _ = domain_policy.check("notexample.com")
+    assert not allowed, "FAIL: Domain match should not match different domain"
+    print("  [PASS] Domain match rejects different domain")
+
+    # Test 6: Glob pattern
+    glob_policy = Policy([AllowRule("*.example.com", "glob")])
+    allowed, _ = glob_policy.check("api.example.com")
+    assert allowed, "FAIL: Glob pattern failed"
+    print("  [PASS] Glob pattern works")
+
+    # Test 7: Glob denies non-matching
+    allowed, _ = glob_policy.check("api.other.com")
+    assert not allowed, "FAIL: Glob should deny non-matching"
+    print("  [PASS] Glob rejects non-matching")
+
+    # Test 8: Case insensitivity
+    allowed, _ = exact_policy.check("EXAMPLE.COM")
+    assert allowed, "FAIL: Policy should be case-insensitive"
+    print("  [PASS] Case insensitive matching")
+
+    # Test 9: Whitespace trimming
+    allowed, _ = exact_policy.check("  example.com  ")
+    assert allowed, "FAIL: Policy should trim whitespace"
+    print("  [PASS] Whitespace trimming works")
+
+    # Test 10: Malformed policy rejection
+    try:
+        Policy.from_dict({"rules": "not-a-list"})
+        assert False, "FAIL: Should reject malformed policy"
+    except ValueError:
+        print("  [PASS] Rejects malformed policy")
+
+    # Test 11: Fail-closed on missing policy file
+    missing_policy = load_policy("/nonexistent/path/policy.json")
+    allowed, _ = missing_policy.check("example.com")
+    assert not allowed, "FAIL: Missing policy file should use empty (deny-all) policy"
+    print("  [PASS] Missing policy file defaults to deny-all")
+
+    print("\nAll self-tests passed!")
+    return 0
+
+def main():
+    """Main CLI entry point."""
+    # GENERATED doctor intercept (gen_aw_doctor.py) -- do not edit
+    _dv = locals().get("argv")
+    if (_dv if _dv is not None else __import__("sys").argv[1:])[:1] == ["doctor"]:
+        from ._doctor import report
+        return report()
+    parser = argparse.ArgumentParser(
+        prog='awwall',
+        description='Egress allowlist that fails closed: declare what a workload '
+                    'may reach, watch everything else fail with the rule that '
+                    'denied it.'
+    )
+
+    parser.add_argument(
+        '--policy-file', type=str,
+        help=f'Policy file (default: {DEFAULT_POLICY_FILE})')
+    parser.add_argument('--self-test', action='store_true', help='Run self-tests')
+
+    subparsers = parser.add_subparsers(dest='command', help='Command to run')
+
+    # allow command
+    allow_parser = subparsers.add_parser('allow', help='Add a host to the allowlist')
+    allow_parser.add_argument('host', help='Hostname to allow')
+    allow_parser.add_argument(
+        '--type', choices=['exact', 'domain', 'glob'],
+        help='Rule type (auto-detect if not specified)')
+    allow_parser.add_argument(
+        '--as-domain', action='store_true',
+        help='Treat as domain rule (default for multi-part hosts)')
+    allow_parser.add_argument('--description', help='Rule description')
+    allow_parser.set_defaults(func=cmd_allow)
+
+    # check command
+    check_parser = subparsers.add_parser('check', help='Check if a host is allowed')
+    check_parser.add_argument('host', help='Hostname to check')
+    check_parser.add_argument(
+        '-v', '--verbose', action='store_true', help='Verbose output')
+    check_parser.set_defaults(func=cmd_check)
+
+    # explain command
+    explain_parser = subparsers.add_parser(
+        'explain', help='Explain why a host is allowed or denied')
+    explain_parser.add_argument('host', help='Hostname to explain')
+    explain_parser.set_defaults(func=cmd_explain)
+
+    # emit command
+    emit_parser = subparsers.add_parser('emit', help='Emit policy in different formats')
+    emit_parser.add_argument(
+        '--format', choices=['hosts', 'iptables', 'json'],
+        default='json', help='Output format')
+    emit_parser.add_argument('--output', help='Output file (default: stdout)')
+    emit_parser.set_defaults(func=cmd_emit)
+
+    # list command
+    list_parser = subparsers.add_parser('list', help='List all rules in the policy')
+    list_parser.set_defaults(func=cmd_list)
+
+    args = parser.parse_args()
+
+    if args.self_test:
+        return cmd_self_test(args)
+    elif hasattr(args, 'func'):
+        return args.func(args)
+    else:
+        parser.print_help()
+        return 0
+
+if __name__ == '__main__':
+    sys.exit(main())
+