hypnguyen1209/offensive-claude / skills/coding-mastery
coding-mastery
VerifiedUse when writing security tooling, exploits, scanners, or C2 in Python/C/Go/Rust/ASM — systems & network programming, automation, cryptography implementation
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.8 KB |
| scripts/_lib/action_guard.py | script | 12.8 KB |
| scripts/_lib/cmd_parser.py | script | 10.9 KB |
| scripts/_lib/http_creds.py | script | 2.9 KB |
| scripts/_lib/private_tag.py | script | 3.9 KB |
| scripts/_lib/redact_headers.py | script | 5.1 KB |
| scripts/_lib/safe_subprocess.py | script | 18.6 KB |
| scripts/_lib/scope_guard.py | script | 11.7 KB |
| scripts/_lib/secret_scan.py | script | 5.7 KB |
| scripts/_lib/unicode_scan.py | script | 4.3 KB |
| scripts/lib.sh | script | 2.0 KB |
scripts/_lib/action_guard.py
View on GitHub#!/usr/bin/env python3
"""action_guard.py - runtime gate for outward actions during an engagement.
A 3-state decision (allow | require_approval | block) for "should this request go out?",
combining four controls so automation and operators can't quietly do something the ROE
forbids or hammer a host into the ground:
1. SCOPE - out-of-scope target -> block (delegates to scope_guard.py).
2. SAFE METHOD- read-only verbs (GET/HEAD/OPTIONS) auto-allow; mutating verbs
(POST/PUT/PATCH/DELETE/...) -> require_approval unless ROE allows them.
3. CIRCUIT - per-host breaker: N consecutive failures -> block the host for a cooldown
(stop pounding a broken/blocking target; classic blue-team tripwire too).
4. RATE LIMIT - optional per-host min-interval pacing.
Design notes vs the framework we borrowed the idea from:
- No confusing "disabled = paranoid" inversion. Explicit flags: `require_approval_all`
(downgrade every allow to require_approval) and `allow_mutating` (ROE opt-in).
- Portable: optional state persistence uses an atomic os.replace temp-write, NOT fcntl.
- Deterministic: time source is injectable (`clock=`), so tests don't sleep.
CLI:
action_guard.py decide --method POST --target https://api.acme.com/x [--scope scope.json]
[--allow-mutating] [--require-approval-all] [--state state.json]
exit 0 = allow, 4 = require_approval, 5 = block, 2 = error
"""
from __future__ import annotations
import argparse
import json
import os
import sys
import time
from dataclasses import dataclass, asdict, field
from typing import Callable, Optional
SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
KNOWN_METHODS = SAFE_METHODS | frozenset({"POST", "PUT", "PATCH", "DELETE", "CONNECT", "TRACE"})
# Engagement-critical config: an *edit* to one of these mid-engagement is the "widen scope /
# neuter a gate to pass" failure mode. Matched by basename (case-insensitive). First-time
# CREATE is allowed (setup); only EDITS of an existing file need a human.
_PROTECTED_CONFIG_BASENAMES = frozenset({
"scope.json", # .engage/scope/scope.json - the in-scope target set
"roe.json", "roe.md", "roe.yaml", "roe.yml", # rules of engagement
"gate.json", "gates.json", "validation.json", # gate / finding-validation config
"settings.json", "settings.local.json", # Claude Code deny lists
})
ALLOW, REQUIRE_APPROVAL, BLOCK = "allow", "require_approval", "block"
_EXIT = {ALLOW: 0, REQUIRE_APPROVAL: 4, BLOCK: 5}
@dataclass
class Decision:
action: str # allow | require_approval | block
reason: str
host: str = ""
method: str = ""
def to_dict(self) -> dict:
return asdict(self)
class CircuitBreaker:
"""Per-host breaker. `threshold` consecutive failures opens it for `cooldown` seconds."""
def __init__(self, threshold: int = 5, cooldown: float = 60.0, clock: Callable[[], float] = time.monotonic):
self.threshold = max(1, int(threshold))
self.cooldown = float(cooldown)
self.clock = clock
self._fails: dict[str, int] = {}
self._opened_at: dict[str, float] = {}
def is_open(self, host: str) -> bool:
opened = self._opened_at.get(host)
if opened is None:
return False
if self.clock() - opened >= self.cooldown:
# cooldown elapsed -> half-open: clear and allow a retry
self._opened_at.pop(host, None)
self._fails[host] = 0
return False
return True
def record_failure(self, host: str) -> None:
self._fails[host] = self._fails.get(host, 0) + 1
if self._fails[host] >= self.threshold:
self._opened_at[host] = self.clock()
def record_success(self, host: str) -> None:
self._fails[host] = 0
self._opened_at.pop(host, None)
def load(self, data: dict) -> None:
# fail CLOSED + resilient: drop only bad entries, and treat an unparseable
# opened_at as "just opened" so a recorded-open host stays BLOCKED.
fails = {}
for k, v in (data.get("fails") or {}).items():
try:
fails[k] = int(v)
except (TypeError, ValueError):
fails[k] = self.threshold
opened = {}
for k, v in (data.get("opened_at") or {}).items():
try:
opened[k] = float(v)
except (TypeError, ValueError):
opened[k] = self.clock()
self._fails = fails
self._opened_at = opened
def dump(self) -> dict:
return {"fails": self._fails, "opened_at": self._opened_at}
class RateLimiter:
"""Optional per-host minimum interval (seconds). rps<=0/None disables it."""
def __init__(self, rps: Optional[float] = None, clock: Callable[[], float] = time.monotonic):
self.min_interval = (1.0 / rps) if rps and rps > 0 else 0.0
self.clock = clock
self._last: dict[str, float] = {}
def allow(self, host: str) -> bool:
if self.min_interval <= 0:
return True
now = self.clock()
last = self._last.get(host)
if last is not None and (now - last) < self.min_interval:
return False
self._last[host] = now
return True
def classify_method(method: str, allow_mutating: bool = False) -> str:
m = (method or "GET").upper()
if m in SAFE_METHODS:
return ALLOW
if allow_mutating:
return ALLOW
return REQUIRE_APPROVAL # mutating or unknown verb -> human in the loop
class ActionGuard:
def __init__(self, scope=None, *, allow_mutating: bool = False, require_approval_all: bool = False,
breaker: Optional[CircuitBreaker] = None, limiter: Optional[RateLimiter] = None):
self.scope = scope
self.allow_mutating = allow_mutating
self.require_approval_all = require_approval_all
self.breaker = breaker or CircuitBreaker()
self.limiter = limiter or RateLimiter()
def _host(self, target: str) -> str:
try:
import scope_guard
return scope_guard.split_host_port(target)[0]
except Exception:
return target
def decide_command(self, command: str) -> Decision:
"""Decide whether a shell command may run. A destructive command (rm -rf, git force-push,
even hidden behind `sh -c`/`$(...)`) -> require_approval (or block under require_approval_all).
Uses cmd_parser's bypass-resistant classifier; reasons name the danger, never the raw args."""
try:
import cmd_parser
v = cmd_parser.is_destructive(command)
except Exception:
v = None
if v is not None and v.destructive:
reason = f"destructive command ({', '.join(v.reasons)})"
# a destructive op always needs a human; require_approval_all hardens it to block
action = BLOCK if self.require_approval_all else REQUIRE_APPROVAL
return Decision(action, reason, "", "")
return Decision(ALLOW, "no destructive pattern detected", "", "")
def decide_config_edit(self, path: str) -> Decision:
"""Decide whether writing `path` may proceed. Editing an EXISTING engagement-critical
config (scope.json, ROE, gate/validation config, settings.json deny lists) -> require_approval
(block under require_approval_all): silently widening scope or neutering a gate to "pass" is
exactly the abuse this stops. First-time CREATE is allowed. Fail-CLOSED: if we cannot stat
the path for any reason other than 'it does not exist', treat it as an edit."""
name = os.path.basename(str(path).replace("\\", "/").rstrip("/")).lower()
if name not in _PROTECTED_CONFIG_BASENAMES:
return Decision(ALLOW, "not an engagement-critical config file", "", "")
try:
os.stat(path)
exists = True
except FileNotFoundError:
exists = False # ENOENT only -> genuine first-time create
except (OSError, ValueError):
exists = True # fail-closed: cannot tell (perm error, NUL byte, ...) -> treat as an edit
if not exists:
return Decision(ALLOW, f"first-time create of {name} (not an edit)", "", "")
action = BLOCK if self.require_approval_all else REQUIRE_APPROVAL
return Decision(action, f"edit to engagement-critical config ({name}) needs approval", "", "")
def decide(self, method: str, target: str) -> Decision:
host = self._host(target)
# 1. scope (out-of-scope is non-negotiable)
if self.scope is not None:
d = self.scope.evaluate(target)
if not d.in_scope:
return Decision(BLOCK, f"out-of-scope: {d.reason}", host, method)
# 2. circuit breaker
if self.breaker.is_open(host):
return Decision(BLOCK, f"circuit breaker open for {host} (too many failures)", host, method)
# 3. rate limit
if not self.limiter.allow(host):
return Decision(BLOCK, f"rate limit exceeded for {host}", host, method)
# 4. method policy
action = classify_method(method, self.allow_mutating)
reason = "read-only method" if action == ALLOW else f"mutating/unknown method {method.upper()} needs approval"
# 5. global gate
if self.require_approval_all and action == ALLOW:
action, reason = REQUIRE_APPROVAL, "require_approval_all is set"
return Decision(action, reason, host, method)
def _load_state(path: Optional[str], breaker: CircuitBreaker) -> None:
if path and os.path.isfile(path):
try:
with open(path, "r", encoding="utf-8") as fh:
breaker.load(json.load(fh).get("breaker", {}))
except (OSError, ValueError):
pass
def _save_state(path: Optional[str], breaker: CircuitBreaker) -> None:
if not path:
return
tmp = f"{path}.tmp{os.getpid()}"
with open(tmp, "w", encoding="utf-8") as fh:
json.dump({"breaker": breaker.dump()}, fh)
os.replace(tmp, path) # atomic, portable (no fcntl)
def main(argv: Optional[list[str]] = None) -> int:
p = argparse.ArgumentParser(description="Runtime action guard (3-state).")
sub = p.add_subparsers(dest="cmd", required=True)
d = sub.add_parser("decide", help="decide whether an action may proceed")
d.add_argument("--method", default="GET")
d.add_argument("--target", required=True)
d.add_argument("--scope", help="scope.json (enables scope enforcement)")
d.add_argument("--allow-mutating", action="store_true", help="ROE permits mutating methods")
d.add_argument("--require-approval-all", action="store_true")
d.add_argument("--state", help="circuit-breaker state file (persisted atomically)")
d.add_argument("--json", action="store_true")
c = sub.add_parser("command", help="decide whether a shell command may run")
c.add_argument("--command", required=True)
c.add_argument("--require-approval-all", action="store_true")
c.add_argument("--json", action="store_true")
cfg = sub.add_parser("config", help="decide whether writing an engagement-config file may proceed")
cfg.add_argument("--path", required=True)
cfg.add_argument("--require-approval-all", action="store_true")
cfg.add_argument("--json", action="store_true")
args = p.parse_args(argv)
if args.cmd in ("command", "config"):
try:
guard = ActionGuard(None, require_approval_all=args.require_approval_all)
dec = (guard.decide_command(args.command) if args.cmd == "command"
else guard.decide_config_edit(args.path))
if args.json:
print(json.dumps(dec.to_dict()))
else:
print(f"{dec.action.upper()}: {dec.reason}")
return _EXIT[dec.action]
except Exception as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
try:
scope = None
if args.scope:
import scope_guard
scope = scope_guard.Scope.load(args.scope)
# wall-clock so persisted opened_at is comparable across CLI invocations
breaker = CircuitBreaker(clock=time.time)
_load_state(args.state, breaker)
guard = ActionGuard(scope, allow_mutating=args.allow_mutating,
require_approval_all=args.require_approval_all, breaker=breaker)
dec = guard.decide(args.method, args.target)
_save_state(args.state, breaker)
if args.json:
print(json.dumps(dec.to_dict()))
else:
print(f"{dec.action.upper()}: {dec.method.upper()} {dec.target if False else args.target} "
f"-> {dec.host} - {dec.reason}")
return _EXIT[dec.action]
except Exception as exc: # never fail OPEN
print(f"error: {exc}", file=sys.stderr)
return 2
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |