MIT Network Audit docs
How it works

Advanced: how capture works

5 min read Odoo 18.0

This page describes how MIT Network Audit captures, labels and stores connections. It is for developers and security engineers who want to judge what the module can and cannot see.

Who this is for: developers and security engineers. You do not need this page to use the module. You need: basic knowledge of Python and Odoo. The module's source code is open, so you can check each statement here.

Before you begin

  1. Read Security and capture limits for the short list of what is not captured.
  2. Know that this page is checked against the Odoo 18 copy of the module. Other versions differ.

The path of one event

  1. A patched function sees a call (an outbound request, a mail command, a socket connect, or an inbound HTTP request).
  2. The module reads the call stack and takes the first Odoo module that is not base, web or this module. Calls from other standard Odoo apps are shown under that app. That module is the Addon of the event.
  3. It masks sensitive header values and applies the redaction policy (strict mode removes path, query names and fingerprints).
  4. It builds an event object that has no body field.
  5. The event goes into an in-memory buffer. A sink saves the buffer to the network.egress_log table in batches, on its own database cursor, so the row is saved even if the business transaction rolls back.
  6. When the row is saved, the module stamps the MIT-bound flag from the Egress Components list, links the module record, and extends the hash chain.
  7. A daily job summarises the rows into the network.egress.rollup table. The Trust Report and Traffic Summary read that table.
flowchart LR
    IN[Inbound HTTP<br/>WSGI wrapper] --> CORE[Interceptor core<br/>no Odoo imports]
    OUT[Outbound patches<br/>requests, urllib, httpx,<br/>smtp, imap, pop3, ssl, socket] --> CORE
    CORE -->|attribute and redact| EV[Event<br/>metadata, no body]
    EV --> BUF[Buffer<br/>up to 5000 events]
    BUF --> LOG[(network.egress_log<br/>hash-chained)]
    LOG --> ROLL[(network.egress.rollup)]
    ROLL --> TR[Trust Report]

Three layers

Layer Content Odoo imports
Interceptor core Channel patches, the event type, header masking, the WSGI wrapper. None. The project checks this in its build.
Glue Attribution, the redaction policy, the database sink, the inbound patch, the optional body tap. Yes
Odoo models The log, the rollup, the component list, settings, the forensic body store, views and security. Yes

You can read and run the core without Odoo. That makes the capture logic easier to review. It does not make the Odoo layer less important.

What is captured

Outbound:

Channel Hook
requests The send function of the HTTP adapter.
urllib The standard-library HTTP client (http.client).
httpx The httpx client.
smtp, imap, pop3 The standard-library mail clients.
ssl Sending on a TLS socket.
socket connect and connect_ex. A last-resort record for libraries that no other channel knows.

Inbound: a wrapper around the Odoo HTTP application, and the accept call of sockets.

What is not captured

  • WebSocket upgrades. They pass straight through and are not recorded, because wrapping them would break Odoo's real-time features.
  • Connections to the same machine. Connections to 127.0.0.1, ::1 and localhost, and Unix sockets, are skipped. This includes PostgreSQL on the same host and a local reverse proxy hop.
  • Other processes. Shell scripts, external cron jobs and subprocesses that do not run inside an Odoo process.
  • Anything while a channel or the master switch is off.
  • Events that are dropped. The buffer holds up to 5,000 events per process. When it is full, new events are dropped. Events are also dropped while a module install or upgrade is running, and in test mode.
  • Calls that happen before the interceptor is installed in a process. See Install MIT Network Audit.

Attribution

The attribution function walks up to 60 stack frames and returns the first frame whose module name starts with odoo.addons., skipping base, web and mit_network_audit. If it finds none, the event has no module and no call site.

  • A call made only by base or web code is not attributed to any module.
  • Code that calls a library on behalf of another module can be attributed to the module that is nearest on the stack.
  • Because mit_network_audit is skipped, a call made by this module itself will usually not be labelled with its name. The Self-egress chip counts rows that are labelled that way, so treat it as a weak signal.

What an event holds

Direction, channel, protocol, method, host, URL path, the names of query parameters, source and destination address and port, status, request and response sizes, time, duration, content types, masked headers, the module and call site, and a salted HMAC fingerprint of method|host|path.

The event type has no body field. A separate, optional body tap can store bodies in network.egress_body, under the forensic settings. It is off by default and needs an allowlist.

Failure behaviour

The module catches errors inside capture, attribution, redaction and the sink so that they do not stop the observed call. The code that does this is in the dispatch function of the interceptor. This is a design goal that the code follows. It has not been proven for every possible fault. In the worst case, a row is missing.

The module's effect on speed has not been measured.

Log, hash chain and summary

  • The network.egress_log model refuses write and unlink in Odoo, except for the retention job. A database trigger also blocks changes to sealed rows, and blocks deletes unless a session flag is set.
  • On create, the module takes a database advisory lock, reads the latest row, and writes chain_seq, prev_hash and row_hash with SQL. The hash is SHA-256 over a fixed list of 19 fields and the previous hash.
  • A daily job signs the latest head with HMAC. The key is stored in the same database. See Verify the log and export evidence.
  • The summary table is derived data. The daily job and the Refresh button recompute the last few days from the log.

Installation routes

The module installs the interceptor in post_load (when it is in server_wide_modules) or from ir.http._register_hook (when a registry loads). Both call one function that runs only once per process. See Install MIT Network Audit.

Next step

What the audit log can and cannot show.