Jj.QdZddlmZddlZddlZddlZddlmZmZddl m Z ddl m Z ddl mZddlmZmZmZmZmZGd d ee ZGd d ee ZeGd dZeGddZGddZgdZy)aAudit - security audit logging and evidence tracking. Audit tracks security-relevant events across the system: - user, agent, task, model, tool, action - policy decision, approval, result, error - resource usage, latency, network action - memory write, security alert **What "immutable" means here, precisely.** Records are hash-chained: each one carries the digest of its predecessor, so an in-place edit, a deletion, a reordering, or a truncation of the beginning is detected and localised by :func:`~cyberbrain26.security_plane.audit.chain.verify_chain`. The chain does **not** make the log impossible to alter. The digest is plain SHA-256 with no secret, so an adversary holding write access to the database can rewrite the log and recompute every link, presenting a chain that verifies perfectly; deleting the end of the chain has the same effect. That is a residual risk tracked in the plan's F6 section, not an oversight. This is also why :meth:`AuditLog.clear` and :meth:`AuditLog.prune_expired` exist and why they are not silent: they are the operations a chain alone cannot make safe, so they mark what they did instead of pretending they did nothing. ) annotationsN) dataclassfield)Enum)Any)SQLiteDatabase)GENESIS TamperClassVerificationReportcompute_event_hash verify_chaincpeZdZdZdZdZdZdZdZdZ dZ d Z d Z d Z d Zd ZdZdZdZdZdZdZdZdZdZdZdZdZy)AuditEventTypezTypes of audit events. user_action agent_startedagent_finished task_created task_started task_finished tool_called tool_resultmodel_discoveredmodel_validated model_failedpolicy_decisionapproval_requiredapproval_grantedapproval_deniedsecurity_alertresource_limitmemory_updatedidentity_checkpermission_checkfirewall_check data_access config_changeerrorN)__name__ __module__ __qualname____doc__ USER_ACTION AGENT_STARTEDAGENT_FINISHED TASK_CREATED TASK_STARTED TASK_FINISHED TOOL_CALLED TOOL_RESULTMODEL_DISCOVEREDMODEL_VALIDATED MODEL_FAILEDPOLICY_DECISIONAPPROVAL_REQUIREDAPPROVAL_GRANTEDAPPROVAL_DENIEDSECURITY_ALERTRESOURCE_LIMITMEMORY_UPDATEDIDENTITY_CHECKPERMISSION_CHECKFIREWALL_CHECK DATA_ACCESS CONFIG_CHANGEERRORP/home/oem/CyberBrain26-unified/src/cyberbrain26/security_plane/audit/__init__.pyrr,s K#M%N!L!L#MKK)'O!L'O+)'O%N%N%N%N)%NK#M ErErceZdZdZdZdZdZy)AuditEventStatuszStatus of an audit event.recorded correlatedarchivedN)r(r)r*r+RECORDED CORRELATEDARCHIVEDrDrErFrHrHIs#HJHrErHc\eZdZUdZded<ded<ded<dZded <dZded <dZded <dZded <dZ ded <dZ ded<dZ ded<dZ ded<dZ ded<dZded<dZded<eeZded<dZded<dZded<dZded<dZded<eeZded<ej2Zded<y) AuditEventzA single audit event.strevent_idr event_typefloat timestampactoragent_idtask_idmodeltoolactionresourcer approval_idresultr')default_factorydict[str, Any]resource_usage latency_msnetwork_action memory_writermetadatarHstatusN)r(r)r*r+__annotations__rWrXrYrZr[r\r]rr^r_r'rdictrbrdrerfrrgrHrLrhrDrErFrPrPQsME3OHcGSE3OD#NFCHcOSKFCE3O%*4%@NN@JNCL#NC$T:Hn:/88F 8rErPceZdZUdZdZded<dZded<dZded<dZded<dZ ded <dZ ded <dZ d ed <dZ d ed <dZ ded<y) AuditQueryz,Query parameters for filtering audit events.NzAuditEventType | NonerSz str | NonerWrXrYr\r] float | Nonesinceuntildintlimit)r(r)r*r+rSrirWrXrYr\r]rnrorrrDrErFrlrlls`6(,J%,E:HjGZFJHjE<E<E3rErlceZdZdZdddZ d ddZeddZddZdddZ ddZ dd Z ddd Z dd Z dd Zd d Zddd!dZd"dZddZed#dZy)$AuditLogamAppend-only, hash-chained audit log for security events. Events are written to `audit_events` and kept in an in-memory list. Each record commits to its predecessor's digest via ``seq``, ``prev_hash`` and ``entry_hash`` (computed with ``compute_event_hash`` from ``cyberbrain26.security_plane.audit.chain``), so corruption, deletion, reordering and prefix truncation are all detectable and localisable. The chain is tamper-evident, not tamper-proof: an attacker with write access can rewrite the log and recompute any digest without the HMAC key (``CYBERBRAIN_CHAIN_KEY``). `clear()` and `prune_expired()` both DELETE rows; the docstring on each method states this explicitly rather than pretending the log is immutable. Usage: audit = AuditLog() audit.record(AuditEventType.SECURITY_ALERT, agent_id="agent-1", security_alert="suspicious activity detected") events = audit.query(agent_id="agent-1") report = audit.verify_chain() if not report.intact: ... **Single writer.** The head digest is read and the new link appended within one transaction, so concurrent writers cannot fork the chain. Two ``AuditLog`` instances writing to the same database in the same process would not be safe; that is a precondition, not something this class enforces. Ncd||_g|_|j|j|_yyN)database_events_load_persisted)selfrws rF__init__zAuditLog.__init__s/  )+ == $//1DL %rEcPtd iddtjjddd|dt jd|d|d |d |d |d |d |d| d| d| d| d| xsid|d|d|d|d|xsi}|j |j j||S|j|}|j j5}|jdj}| dt}}d}n|d}|d}t|dz}||d<||d<t|||d<|jd|j|j j"|j$|j&|j(|j*|j,|j.|j0|j2|j4|j6|j8|j:t=j>|j@d|jB|jD|jF|jHt=j>|jJd|jLj"|d|d|dfddd|j j||S#1swY&xYw)!aRecord a new audit event, linked to the current head of the chain. The head digest is read and the new link appended inside one transaction, so two writers cannot both claim the same predecessor. Every field that goes into the digest is the same value that is persisted, which is what lets a verifier recompute the chain from the stored row alone. rRaudit_NrSrUrWrXrYrZr[r\r]rr^r_r'rbrdrerfrrgz_SELECT seq, entry_hash FROM audit_events WHERE entry_hash IS NOT NULL ORDER BY seq DESC LIMIT 1seq entry_hash prev_hasha  INSERT INTO audit_events( event_id, event_type, timestamp, actor, agent_id, task_id, model, tool, action, resource, policy_decision, approval_id, result, error, resource_usage_json, latency_ms, network_action, memory_write, security_alert, metadata_json, status, seq, prev_hash, entry_hash ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ,: separatorsrD)'rPuuiduuid4hextimerwrxappend _chain_fields transactionexecutefetchoner rqr rRrSvaluerUrWrXrYrZr[r\r]rr^r_r'jsondumpsrbrdrerfrrgrh)rzrSrWrXrYrZr[r\r]rr^r_r'rbrdrerfrrgeventrow connectionhead previous_seqrnext_seqs rFrecordzAuditLog.records8 djjl..s345 ! iik           , $   */R "! "*# $&% &*' (^) . ==  LL   &L  ' ]] & & (5 J%%Ihj |*.i #E{  . |,q0!CJ(C  23 BC    NN$$**OOKKNNMMKKJJLLNN))%%LLKKJJu33 K$$((&&((JJu~~*ELL&&J $ %1$ #5 n E" q5 5 s F!JJ%cid|jd|jjd|jd|jd|j d|j d|jd|jd |jd |jd |jd |jd |jd|jdtj |j"dd|j$d|j&|j(|j*tj |j,d|j.jdS)zThe record as the chain sees it: every column, JSON columns flattened. The digest must be computable from the stored row alone, so nested structures are encoded exactly as ``_load_persisted`` will decode them. rRrSrUrWrXrYrZr[r\r]rr^r_r'resource_usage_jsonrrrdre)rfr metadata_jsonrh)rRrSrrUrWrXrYrZr[r\r]rr^r_r'rrrbrdrerfrrgrh)rs rFrzAuditLog._chain_fieldssp  %**00    U[[    u}}   U[[  EJJ  ell    u44  5,,  ell  U[[  "4::$$$ $ %**% & e22' ("..#22!ZZ:Nll((/  rEcl|j|jD]}|j|k(s|cSy)zRetrieve an event by its ID.N)_refresh_persistedrxrR)rzrRrs rFgetz AuditLog.get6s7 !\\ E~~)  rEc4|j|xs t}g}|jD]F}|j|j|jk7r*|j|j|jk7rP|j |j |j k7rv|j |j |j k7r|j|j|jk7r|j|j|jk7r|j|j|jkr|j|j|jkDr6|j|I|jdd|d|jS)zQuery events with optional filters. Returns events matching all specified criteria, most recent first, limited by params.limit. Nc|jSrvrUes rFz AuditLog.query..\s 1;;rETkeyreverse)rrlrxrSrWrXrYr\r]rnrUrorsortrr)rzparamsresultsrs rFqueryzAuditLog.query>sJ !':<$&\\ "E  ,1A1AVEVEV1V||'EKK6<<,G*u~~/P~~)emmv~~.M}}(U\\V]]-J*u~~/P||'EOOfll,J||'EOOfll,J NN5 !% "(  . =~&&rEcL|jt|jS)z Total number of recorded events.)rlenrxrzs rFcountzAuditLog.count_s !4<<  rEc`|jtfd|jDS)z Count events of a specific type.c3BK|]}|jk(sdyw)rN)rS).0rrSs rF z)AuditLog.count_by_type..gsIallj.H1Is)rsumrx)rzrSs `rF count_by_typezAuditLog.count_by_typeds$ !IdllIIIrEc^|jt|jdd}|d|S)z#List all events, most recent first.c|jSrvrrs rFrz#AuditLog.list_all..ls AKKrETrN)rsortedrx)rzrreventss rFlist_allzAuditLog.list_allis- ! *?Nfu~rEc|jj|j5|jj5}|j ddddyy#1swYyxYw)azDelete every event. NOT a chain operation - it severs the chain. This exists for tests and fixtures. Calling it on a live log destroys the evidence a chain exists to protect, and no chain can report that, because there is nothing left to verify. That is the honest limitation, and it is why this method is not silent about what it does. NzDELETE FROM audit_events)rxclearrwrr)rzrs rFrzAuditLog.clearos^  == $**, ? ""#=> ? ? % ? ?s AA&c |jgS|jj5}|jdjd}|r |jdj }n|jdj }dddg}D]}|j id|dd|dd|dd |d d |d d |d d |d d |d d|dd|dd|dd|dd|dd|dd|dd|dd|d|d|d|d|d|d|d|dd|S#1swYxYw)aHReturn persisted records in chain order, shaped as the chain sees them. Ordered by ``seq`` when a chain exists, and by timestamp otherwise, so a pre-chain (epoch 0) log still verifies as a declared boundary instead of as a broken link. Two literal queries rather than one interpolated ``ORDER BY``: an f-string in SQL is not injectable here (the clause is a fixed literal), but it reads as if it were, and the next person to "fix" that reading would introduce the hole. Interpolation is avoided for that reason alone. Nz