proc_jail 0.1.0

Process execution guard for agentic systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

"""Type stubs for proc_jail."""

from typing import Dict, List, Optional

class RiskyBinPolicy:
    """Policy for handling risky binaries (shells, interpreters, etc.)."""
    DenyByDefault: RiskyBinPolicy
    AllowWithWarning: RiskyBinPolicy
    Disabled: RiskyBinPolicy

class InjectDoubleDash:
    """Mode for double-dash injection."""
    Never: InjectDoubleDash
    AfterFlags: InjectDoubleDash

class RiskCategory:
    """Category of risky binary."""
    Shell: RiskCategory
    Interpreter: RiskCategory
    Spawner: RiskCategory
    Privilege: RiskCategory

class ArgRules:
    """Rules for validating arguments to a binary."""
    
    def __init__(self) -> None: ...
    def subcommand(self, cmd: str) -> "ArgRules": ...
    def allowed_flags(self, flags: List[str]) -> "ArgRules": ...
    def max_flags(self, max: int) -> "ArgRules": ...
    def max_positionals(self, max: int) -> "ArgRules": ...
    def inject_double_dash(self, mode: InjectDoubleDash) -> "ArgRules": ...

class ProcRequest:
    """A proposed process execution request."""
    
    bin: str
    argv: List[str]
    
    def __init__(
        self,
        bin: str,
        argv: List[str],
        env: Optional[Dict[str, str]] = None,
        cwd: Optional[str] = None,
    ) -> None: ...
    def with_cwd(self, cwd: str) -> "ProcRequest": ...
    def with_env(self, env: Dict[str, str]) -> "ProcRequest": ...
    def with_env_var(self, key: str, value: str) -> "ProcRequest": ...

class Output:
    """Output from command execution."""
    
    @property
    def stdout(self) -> bytes: ...
    @property
    def stderr(self) -> bytes: ...
    @property
    def exit_code(self) -> Optional[int]: ...
    @property
    def success(self) -> bool: ...
    def stdout_string(self) -> str: ...
    def stderr_string(self) -> str: ...

class PreparedCommand:
    """A validated command ready for execution."""
    
    @property
    def bin(self) -> str: ...
    @property
    def argv(self) -> List[str]: ...
    def spawn_sync(self) -> Output: ...

class ProcPolicy:
    """Policy for process execution."""
    
    def prepare(self, request: ProcRequest) -> PreparedCommand: ...

class ProcPolicyBuilder:
    """Builder for ProcPolicy."""
    
    def __init__(self) -> None: ...
    def allow_bin(self, path: str) -> "ProcPolicyBuilder": ...
    def arg_rules(self, path: str, rules: ArgRules) -> "ProcPolicyBuilder": ...
    def risky_bin_policy(self, policy: RiskyBinPolicy) -> "ProcPolicyBuilder": ...
    def env_empty(self) -> "ProcPolicyBuilder": ...
    def env_locale_only(self) -> "ProcPolicyBuilder": ...
    def env_fixed(self, env: Dict[str, str]) -> "ProcPolicyBuilder": ...
    def env_allowlist(self, keys: List[str]) -> "ProcPolicyBuilder": ...
    def cwd(self, path: str) -> "ProcPolicyBuilder": ...
    def timeout_secs(self, seconds: int) -> "ProcPolicyBuilder": ...
    def max_stdout(self, bytes: int) -> "ProcPolicyBuilder": ...
    def max_stderr(self, bytes: int) -> "ProcPolicyBuilder": ...
    def build(self) -> ProcPolicy: ...