JjYUdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z ddl m Z mZddlmZddlmZgd Zd Zd ed <d Zded<dddddZded<eddhZded<ej4dZded<dZd ed<ej4d Zded!<Gd"d#eZd/d$Zd0d%Z d1d&Z!d2d'Z"d3d(Z#e d)*Gd+d,Z$e d)*Gd-d.Z%y)4uEngagement scope and owner authorization for the pentest agent. This module owns the two pieces of state a penetration test needs and the current policy language cannot express: * :class:`TargetScope` — the whitelist of hosts/CIDRs a test may touch, and * :class:`EngagementAuthorization` — the artifact a human signed off on. Why this is code and not a policy rule -------------------------------------- The policy DSL evaluates a boolean expression over an AST allowlist (``security_plane/policy/__init__.py``); a condition has to be a bool no longer than 256 characters and may only call ``is_sensitive``. "Is this address inside the approved range" is a function call returning a bool, so it *looks* expressible — but writing it would mean either giving up that allowlist or smuggling the range into a string. Both are worse than a typed object with its own tests, so the whitelist is a value with a real parser, and it is consulted on **every** tool invocation rather than once per session. Scope decisions that are security properties, not conveniences ------------------------------------------------------------- * An empty scope authorises nothing. ``TargetScope`` with no networks and no hosts refuses every target; there is no "no scope configured means allow". * A target may only be a single host, a ``host:port`` pair, or an ``http(s)`` URL. Credentials in the authority (``http://user:pw@host``), control characters, whitespace and shell metacharacters are refused outright, because the target text ends up in a process argument vector. * A CIDR mask **in a tool target** is accepted only when the resulting network is a subnet of an authorised network. Checking only the address would let ``10.0.0.0/8`` through a scope of ``10.0.0.0/24``, which is the obvious way to bypass a whitelist and the reason the mask is validated, not stripped. * Host *names* are accepted only when the name itself was listed in the engagement. Names are not resolved during authorization: resolving here would make the check depend on DNS the caller controls (rebinding between the check and the run), so a name is either explicitly authorised or refused. ) annotationsN)Iterable) dataclass)AnyFinal)urlsplit) SecurityError)MAX_ENGAGEMENT_LEVEL TOOL_CLASSESTOOL_CLASS_BY_LEVELEngagementAuthorization TargetScopeTargetScopeErrorz Final[int]r )passiverecon vulnerability exploitationzFinal[tuple[str, ...]]r rrrr)rrzFinal[dict[int, str]]r httphttpszFinal[frozenset[str]]_ALLOWED_URL_SCHEMESz'^[a-z0-9]([a-z0-9._-]{0,251}[a-z0-9])?$zFinal[re.Pattern[str]] _HOSTNAME_RE_MAX_TARGET_LENGTHz^0[xX][0-9a-fA-F]+$ _HEX_ONLY_REceZdZdZy)rzA target is unusable or lies outside the authorised engagement scope. Inherits from ``SecurityError`` so a caller can refuse on the same signal the rest of the security plane uses; every instance is a refusal, never a recoverable error. N)__name__ __module__ __qualname____doc__D/home/oem/CyberBrain26-unified/src/cyberbrain26/agents/engagement.pyrrVsr$rcN tj|y#t$rYywxYw)NFT) ipaddress ip_address ValueErrorhosts r%_is_ip_literalr,_s.T"  s  $$c^|j}|jdrR|jd}|dk(rtd||d|}||dzd}|r~|jdsmtd||j ddk(rI|j d\}}}|j rdt|cxkrd ksntd ||}|jj}|s td t|s$tj|std |d |S)zFReturn the bare host of an authority component, refusing anything odd.[]z"malformed IPv6 literal in target: rN:riz)target port is not a valid TCP/UDP port: ztarget carries no host partz target host z) is neither an IP literal nor a host name) strip startswithfindrcount partitionisdigitintlowerr,rmatch)netlocvalueendr+ remainder_ports r%_host_from_netlocrAgs* LLNE jjo "9"%Gz#RS SQs|#')$ Y11#6"%Gz#RS S S Q , a||~QT%:U%:"%Nth#WX X ::<   D <== $  (:(:4(@dX5^_`` Kr$cd|vryd|vrd|jd}|dk(rtd|||dzd}|dk(s2|jd r|ddjstd |yd |vry|j d \}}}|r|jstd |t |}d |cxkrdksntd||S)aReturn the CIDR prefix length a target declares, or ``None``. A ``/`` is only meaningful on the network part of a literal address. A URL path (``http://host/x``) is not a mask, so the split happens on the raw text only when the text is not a URL. A bracketed IPv6 authority (``[2001:db8::1]:443``) is not a mask either, and returns ``None``. Anything after the closing bracket other than a port is refused outright rather than ignored: dropping the tail would silently turn ``[2001:db8::1]/64`` into a bare address, and a single-address engagement would then authorise 2**64 addresses to a tool that reads the same text as ``addr/prefix``. Refusing keeps "one string, one parser". ://Nr.r/r0zunbalanced bracket in target: rr1z?target must not carry anything after a bracketed IPv6 literal: /zmalformed CIDR in target: rz$CIDR prefix out of range in target: )r4rr3r7r6r8)targetclosingtail address_partr? prefix_textprefixs r% _prefix_ofrMs  f}++c" b="%CF:#NO Ogkm$ ts3QR8H8H8J"QRXQ[\  &#)#3#3C#8 L![ {224!;F:FGG  F  # !EfZPQQ Mr$ct|ts td|j}|s tdt |t kDrtdt dt d|Dr tdd|vr t|}|jjtvr)td |jd ttd d |jvr tdtt|jS|j!dd}tt|S#t$r}td||d }~wwxYw)u Return the host of ``target``, refusing anything that is not a plain host. Accepts ``host``, ``host:port``, ``[v6]:port``, ``10.0.0.0/24`` and ``http(s)://host[:port]/path``. Everything else — a non-string, an empty string, embedded whitespace or control characters, an unsupported URL scheme, credentials in the authority — is a :class:`TargetScopeError`, because each of those is a way to make the text in the argument vector mean something other than the address the reviewer approved. ztarget must be a stringztarget must not be emptyztarget is longer than z charactersc3\K|]$}|jxst|dk&yw) N)isspaceord).0 characters r% z&extract_target_host..s* NI9    7#i.4"7 7 Ns*,z8target must not contain whitespace or control charactersrCz!target is not a well-formed URL: Nztarget URL scheme z is not allowed (allowed: )@z2target must not carry credentials in its authorityrEr) isinstancestrrr2lenranyrr)schemer9rsortedr;_reject_numeric_hostrAr6)rGtextpartsexcrJs r%extract_target_hostrbsP fc "899 <<>D 9:: 4y%%!78J7K;WXX N NNYZZ } ZTNE <<   '; ;"$U\\$45#$89:!=  %,, "#WX X#$5ell$CDD>>#&q)L  1, ? @@ Z"%Fth#OPVY Y Zs D33 E<E  Ecp|r3|jstj|rtd||S)aRefuse a host part that is only digits or only hex digits. ``2130706433`` and ``0x7f000001`` are not host names and are not :func:`ipaddress.ip_address` literals either, so they survive every other check here and then reach the tool, which resolves them numerically - to loopback, in the case of the two examples above. Refusing them at the boundary keeps "the string we checked" and "the string the tool reads" the same string, instead of relying on the tool to agree with us about syntax. z0target host must not be a bare numeric address: )r7r fullmatchrr*s r%r^r^s: <#9#9$#?>th G   Kr$T)frozenczeZdZUdZdZded<eZded<ddZe ddZ dd Z dd Z dd Z dd Zy )raKWhitelist of networks and hosts a pentest tool call may address. Checked on every invocation from :func:`authorize_tool_call` in ``agents.pentest_catalog``; never once per session. Construct it from the signed engagement artifact with :meth:`from_targets` rather than by hand, so the whitelist and the artifact cannot disagree. Attributes: networks: Parsed CIDR networks. Empty means "no network target". hosts: Individually authorised hosts (literal IPs and names). An IP listed here does not imply its /24; only ``networks`` does. r#ztuple[Any, ...]networksfrozenset[str]hostscg}|jD]n}t|j}|s td t j |d}|jdk(rtd||j|ptj|dt|tj|dtd |jDy#t $r}td||d}~wwxYw) Nz0engagement scope contains an empty network entryFstrictz"invalid CIDR in engagement scope: rz.engagement scope must not be a default route: rgric3jK|]+}t|jj-ywNrYr2r9)rSr+s r%rUz,TargetScope.__post_init__.. s$$V4SY__%6%<%<%>$V13)rgrYr2rr' ip_networkr) prefixlenappendobject __setattr__tuple frozensetri)selfparsedrawr_networkras r% __post_init__zTargetScope.__post_init__s== #Cs8>>#D&'YZZ _#..tEB  A%&DTHM MM' "# #$ 4U6]; '9$V4::$VV  _&)KD8'TU[^^ _sC C/C**C/cg}g}|D]}t|j}|s tdt|}t |}||j |S t j|d|d}|jdk(r|j ||j |jd|j|s |s td|t|t| S#t$r} td|| d} ~ wwxYw) zBuild a scope from the target list an engagement was signed off on. A bare literal IP becomes a ``/32`` host entry rather than a network, so listing one address never widens into its surrounding prefix. z#engagement target must not be emptyNrEFrkz#invalid CIDR in engagement target: rz2engagement scope is empty; it authorises no target)rgri)rYr2rrbrMrsr'rqr) num_addressesnetwork_addressrrrvrw) clstargetsrgrirzr_r+rLr{ras r% from_targetszTargetScope.from_targetss! RCs8>>#D&'LMM&t,D%F~ T" `#..$q/A%P$$) T"7#:#:";1W=N=N##D) ) **dV1VH+=eLG%%g..      s"(A+A:+ A76A7: BBcD|jD]}|j|jk7rt|tjtj fr||vsLyt|tj tjfr||k(s|j|syyy)NTF) rgversionrXr' IPv4Address IPv6Address IPv4Network IPv6Network subnet_of)rxrr{s r%rzTargetScope._network_containsQs}} G  GOO3)i&;&;Y=R=R%ST'I (=(=y?T?T'UV'9+>+>w+G r$NreturnNone)rzIterable[object]rr)rrr+rYrr)rGrtrr)rz]ipaddress.IPv4Address | ipaddress.IPv6Address | ipaddress.IPv4Network | ipaddress.IPv6Networkrr)rr r!r"rg__annotations__rwrir| classmethodrrrrrr#r$r%rrsb !#Ho"%KE>' 2EE:1 //(   r$rceZdZUdZded<ded<dZded<ed hZd ed <d Zd ed<d Z d ed<dZ ded<dZ ded<ddZ e ddZddZe ddZd d!dZd"dZd#dZd"dZy )$r aThe artifact a human authorised a pentest engagement under. Everything a reviewer needs in order to say yes or no is a field here, and :attr:`digest` is a stable fingerprint of all of it. The digest is what the operator re-states on the command line and what the audit trail records, so a run cannot quietly happen under different terms than the ones that were shown. Attributes: owner: Human or system accountable for the engagement. targets: The authorised target list; the scope is derived from it. max_level: Highest engagement level permitted (0-3). allowed_tool_classes: Tool classes this engagement may use. Must include the class belonging to ``max_level``. window_start: POSIX timestamp the engagement opens, or ``None``. window_end: POSIX timestamp the engagement closes, or ``None``. intensity: Free-form operator label recorded in the artifact. rules_of_engagement: Human-readable constraints, recorded verbatim. rYownerztuple[str, ...]rrr8 max_levelrrhallowed_tool_classesN float | None window_start window_endmeasured intensityr#rules_of_engagementcFt|jj}|s tdtj |d|t d|jD}|rtd|Dr td|D] }t|tj |d|t|jtst|jtstd|jd|jcxkr tks!ntd td |jtd |j D}|t#t$z }|r(td t'|d t)t$d|s tdtj |d|dD]F}t+||}|t|tst|tt,fr9td|d|j.0|j0$|j.|j0k\r tdtj |dt|j2jxsdtj |dt d|j4Dy)Nz"engagement owner must not be emptyrc3NK|]}t|jywrn)rYr2rSrGs r%rUz8EngagementAuthorization.__post_init__..sGF ))+Gs#%c3"K|]}|  ywrnr#rs r%rUz8EngagementAuthorization.__post_init__..s?V&j?s z2engagement must name at least one non-empty targetrz-engagement max_level must be an integer, got rz+engagement max_level must be between 0 and z, got c3jK|]+}t|jj-ywrnro)rSnames r%rUz8EngagementAuthorization.__post_init__..s$\$CIOO-335\rpz#unknown engagement tool class(es): z (known: rVz-engagement must allow at least one tool classr)rrz engagement z" must be a POSIX timestamp or Nonez1engagement window_start must be before window_endrrrc32K|]}t|ywrn)rY)rSrules r%rUz8EngagementAuthorization.__post_init__..sA#d)As)rYrr2rrtrurvrr[rbrXrrr8r rwrsetr r]listgetattrfloatrrrr)rxrrrGclassesunknownrr<s r%r|z%EngagementAuthorization.__post_init__saDJJ%%'"#GH H4%0G$,,GG#?w??"#WX X (F  ' ( 4G4 dnnd +:dnnc3R"%RSWSaSaRd#ef fDNN:&::"=>R=ST~~&(  \$B[B[\\C -- "5fWo5FG -.a1 "#RS S4!7A2 _DD$'E j&=ZPUX[]bWcEd&TF:\']^^ _    )+!!T__4"#VW W4c$...A.G.G.I.WZX  ! A(@(@A A r$c@tj|jS)z2Return the whitelist derived from :attr:`targets`.)rrrrs r%scopezEngagementAuthorization.scopes'' 55r$c |jt|j|jt |j |j |j|jt|jdS)zDReturn the artifact as a JSON-compatible mapping, order-independent.)rrrrrrrr) rrrrr]rrrrrrs r% canonicalz!EngagementAuthorization.canonicals[ZZDLL)$*4+D+D$E --//#'(@(@#A  r$ctj|jddt}t j |j djS)usReturn a stable SHA-256 fingerprint of the whole artifact. Stable means: two artifacts with the same terms produce the same digest, and any change to any term — including the rules of engagement text — produces a different one. It is a fingerprint, not a signature: it proves the terms did not change, not who agreed to them. T),r1) sort_keys separatorsdefaultzutf-8)jsondumpsrrYhashlibsha256encode hexdigest)rxmaterials r%digestzEngagementAuthorization.digestsE:: NN S ~~hoog67AACCr$c|tjn|}|j||jkry|j||jkDryy)z4Report whether the engagement's time window is open.FT)timerr)rxnowmoments r% is_activez!EngagementAuthorization.is_activesJ #     (Vd6G6G-G ?? &6DOO+Cr$cxt|tst|tsyd|cxkxr|jkScS)zAReport whether ``level`` is at or below the engagement's ceiling.Fr)rXrr8r)rxlevels r% allows_levelz$EngagementAuthorization.allows_levels2 eT "*UC*@E+T^^++++r$cV|jj|jvS)z3Report whether the engagement permits a tool class.)r2r9r)rx tool_classs r%allows_tool_classz)EngagementAuthorization.allows_tool_classs%!'')T-F-FFFr$ct|tst|tsy|j|sytj t|}|y|j |S)aZReport whether one tool invocation at ``level`` is permitted. Both halves have to hold: the level is at or below ``max_level`` *and* the tool class that level belongs to is in ``allowed_tool_classes``. Checking only the number would let an engagement that set ``max_level=3`` silently inherit exploitation even when it named only recon. ``level`` is narrowed rather than coerced. ``int("2")``, ``int(2.0)`` and ``int(True)`` all produce an int, so a blind conversion would turn a malformed declaration into an authorised one and would let anything with ``__int__`` decide its own level. A value that is not already a plain int - a bool included, because ``isinstance(True, int)`` is True - is refused here, which is the same rule :meth:`allows_level` applies. F)rXrr8rr getr)rxrrs r% engages_levelz%EngagementAuthorization.engages_levelsY eT "*UC*@  '(,,SZ8  %%j11r$r)rr)rzdict[str, Any])rrYrn)rrrr)rrtrr)rrYrr)rr r!r"rrrwrrrrrr|propertyrrrrrrrr#r$r%r r gs( J Is+4gY+?.?!%L,%#J #Is+--2 h66   D D, G2r$r r)r;rYrrY)rGrYrz int | None)rGrtrrY)r+rYrrY)&r" __future__rrr'rrercollections.abcr dataclassesrtypingrr urllib.parser&cyberbrain26.security_plane.permissionr __all__r rr r rwrcompilerrrrr,rArMrbr^rr r#r$r%rs*#J# $!!@ $%j$ (] $\  .*/88I.J+J'1rzz2\'] $]!$J$'1rzz2H'I $I}4"J*AZ" $D $\2\2\2r$