:tocdepth: 3 base/protocols/http/main.zeek ============================= .. zeek:namespace:: HTTP Implements base functionality for HTTP analysis. The logging model is to log request/response pairs and all relevant metadata together in a single record. :Namespace: HTTP :Imports: :doc:`base/frameworks/tunnels `, :doc:`base/protocols/conn/removal-hooks.zeek `, :doc:`base/utils/files.zeek `, :doc:`base/utils/numbers.zeek ` Summary ~~~~~~~ Runtime Options ############### ================================================================================ ==================================================================== :zeek:id:`HTTP::default_capture_password`: :zeek:type:`bool` :zeek:attr:`&redef` This setting changes if passwords used in Basic-Auth are captured or not. :zeek:id:`HTTP::http_methods`: :zeek:type:`set` :zeek:attr:`&redef` A list of HTTP methods. :zeek:id:`HTTP::max_pending_requests`: :zeek:type:`count` :zeek:attr:`&redef` Only allow that many pending requests on a single connection. :zeek:id:`HTTP::proxy_headers`: :zeek:type:`set` :zeek:attr:`&redef` A list of HTTP headers typically used to indicate proxied requests. ================================================================================ ==================================================================== Types ##### ============================================= =================================================================== :zeek:type:`HTTP::Info`: :zeek:type:`record` The record type which contains the fields of the HTTP log. :zeek:type:`HTTP::State`: :zeek:type:`record` Structure to maintain state for an HTTP connection with multiple requests and responses. :zeek:type:`HTTP::Tags`: :zeek:type:`enum` Indicate a type of attack or compromise in the record to be logged. ============================================= =================================================================== Redefinitions ############# ==================================================================== ============================================================= :zeek:type:`Log::ID`: :zeek:type:`enum` * :zeek:enum:`HTTP::LOG` :zeek:type:`connection`: :zeek:type:`record` :New Fields: :zeek:type:`connection` http: :zeek:type:`HTTP::Info` :zeek:attr:`&optional` http_state: :zeek:type:`HTTP::State` :zeek:attr:`&optional` :zeek:id:`likely_server_ports`: :zeek:type:`set` :zeek:attr:`&redef` ==================================================================== ============================================================= Events ###### ============================================= ==================================================================== :zeek:id:`HTTP::log_http`: :zeek:type:`event` Event that can be handled to access the HTTP record as it is sent on to the logging framework. ============================================= ==================================================================== Hooks ##### ============================================================== ======================= :zeek:id:`HTTP::finalize_http`: :zeek:type:`Conn::RemovalHook` HTTP finalization hook. :zeek:id:`HTTP::log_policy`: :zeek:type:`Log::PolicyHook` ============================================================== ======================= Detailed Interface ~~~~~~~~~~~~~~~~~~ Runtime Options ############### .. zeek:id:: HTTP::default_capture_password :source-code: base/protocols/http/main.zeek 25 25 :Type: :zeek:type:`bool` :Attributes: :zeek:attr:`&redef` :Default: ``F`` This setting changes if passwords used in Basic-Auth are captured or not. .. zeek:id:: HTTP::http_methods :source-code: base/protocols/http/main.zeek 120 120 :Type: :zeek:type:`set` [:zeek:type:`string`] :Attributes: :zeek:attr:`&redef` :Default: :: { "POST", "PUT", "CONNECT", "BMOVE", "SEARCH", "TRACE", "LOCK", "PROPPATCH", "HEAD", "OPTIONS", "POLL", "REPORT", "SUBSCRIBE", "MOVE", "GET", "UNLOCK", "DELETE", "COPY", "MKCOL", "PROPFIND" } A list of HTTP methods. Other methods will generate a weird. Note that the HTTP analyzer will only accept methods consisting solely of letters ``[A-Za-z]``. .. zeek:id:: HTTP::max_pending_requests :source-code: base/protocols/http/main.zeek 141 141 :Type: :zeek:type:`count` :Attributes: :zeek:attr:`&redef` :Default: ``100`` Only allow that many pending requests on a single connection. If this number is exceeded, all pending requests are flushed out and request/response tracking reset to prevent unbounded state growth. .. zeek:id:: HTTP::proxy_headers :source-code: base/protocols/http/main.zeek 107 107 :Type: :zeek:type:`set` [:zeek:type:`string`] :Attributes: :zeek:attr:`&redef` :Default: :: { "CLIENT-IP", "X-FORWARDED-FROM", "VIA", "XROXY-CONNECTION", "PROXY-CONNECTION", "X-FORWARDED-FOR", "FORWARDED" } A list of HTTP headers typically used to indicate proxied requests. Types ##### .. zeek:type:: HTTP::Info :source-code: base/protocols/http/main.zeek 28 89 :Type: :zeek:type:`record` ts: :zeek:type:`time` :zeek:attr:`&log` Timestamp for when the request happened. uid: :zeek:type:`string` :zeek:attr:`&log` Unique ID for the connection. id: :zeek:type:`conn_id` :zeek:attr:`&log` The connection's 4-tuple of endpoint addresses/ports. trans_depth: :zeek:type:`count` :zeek:attr:`&log` Represents the pipelined depth into the connection of this request/response transaction. method: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Verb used in the HTTP request (GET, POST, HEAD, etc.). host: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Value of the HOST header. uri: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` URI used in the request. referrer: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Value of the "referer" header. The comment is deliberately misspelled like the standard declares, but the name used here is "referrer", spelled correctly. version: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Value of the version portion of the reply. If you require message-level detail, consider the :zeek:see:`http_request` and :zeek:see:`http_reply` events, which report each message's version string. user_agent: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Value of the User-Agent header from the client. origin: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Value of the Origin header from the client. request_body_len: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` Actual uncompressed content size of the data transferred from the client. response_body_len: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` Actual uncompressed content size of the data transferred from the server. status_code: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional` Status code returned by the server. status_msg: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Status message returned by the server. info_code: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional` Last seen 1xx informational reply code returned by the server. info_msg: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Last seen 1xx informational reply message returned by the server. tags: :zeek:type:`set` [:zeek:type:`HTTP::Tags`] :zeek:attr:`&log` A set of indicators of various attributes discovered and related to a particular request/response pair. username: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Username if basic-auth is performed for the request. password: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` Password if basic-auth is performed for the request. capture_password: :zeek:type:`bool` :zeek:attr:`&default` = :zeek:see:`HTTP::default_capture_password` :zeek:attr:`&optional` Determines if the password will be captured for this request. proxied: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&log` :zeek:attr:`&optional` All of the headers that may indicate if the request was proxied. range_request: :zeek:type:`bool` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional` Indicates if this request can assume 206 partial content in response. orig_fuids: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) An ordered vector of file unique IDs. Limited to :zeek:see:`HTTP::max_files_orig` entries. orig_filenames: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) An ordered vector of filenames from the client. Limited to :zeek:see:`HTTP::max_files_orig` entries. orig_mime_types: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) An ordered vector of mime types. Limited to :zeek:see:`HTTP::max_files_orig` entries. resp_fuids: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) An ordered vector of file unique IDs. Limited to :zeek:see:`HTTP::max_files_resp` entries. resp_filenames: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) An ordered vector of filenames from the server. Limited to :zeek:see:`HTTP::max_files_resp` entries. resp_mime_types: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) An ordered vector of mime types. Limited to :zeek:see:`HTTP::max_files_resp` entries. current_entity: :zeek:type:`HTTP::Entity` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) The current entity. orig_mime_depth: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) Current number of MIME entities in the HTTP request message body. resp_mime_depth: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` (present if :doc:`/scripts/base/protocols/http/entities.zeek` is loaded) Current number of MIME entities in the HTTP response message body. client_header_names: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/policy/protocols/http/header-names.zeek` is loaded) The vector of HTTP header names sent by the client. No header values are included here, just the header names. server_header_names: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional` (present if :doc:`/scripts/policy/protocols/http/header-names.zeek` is loaded) The vector of HTTP header names sent by the server. No header values are included here, just the header names. omniture: :zeek:type:`bool` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional` (present if :doc:`/scripts/policy/protocols/http/software-browser-plugins.zeek` is loaded) Indicates if the server is an omniture advertising server. flash_version: :zeek:type:`string` :zeek:attr:`&optional` (present if :doc:`/scripts/policy/protocols/http/software-browser-plugins.zeek` is loaded) The unparsed Flash version, if detected. cookie_vars: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&optional` :zeek:attr:`&log` (present if :doc:`/scripts/policy/protocols/http/var-extraction-cookies.zeek` is loaded) Variable names extracted from all cookies. uri_vars: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&optional` :zeek:attr:`&log` (present if :doc:`/scripts/policy/protocols/http/var-extraction-uri.zeek` is loaded) Variable names from the URI. The record type which contains the fields of the HTTP log. .. zeek:type:: HTTP::State :source-code: base/protocols/http/main.zeek 93 104 :Type: :zeek:type:`record` pending: :zeek:type:`table` [:zeek:type:`count`] of :zeek:type:`HTTP::Info` Pending requests. current_request: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` Current request in the pending queue. current_response: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` Current response in the pending queue. trans_depth: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional` Track the current deepest transaction. This is meant to cope with missing requests and responses. Structure to maintain state for an HTTP connection with multiple requests and responses. .. zeek:type:: HTTP::Tags :source-code: base/protocols/http/main.zeek 18 22 :Type: :zeek:type:`enum` .. zeek:enum:: HTTP::EMPTY HTTP::Tags Placeholder. .. zeek:enum:: HTTP::URI_SQLI HTTP::Tags (present if :doc:`/scripts/policy/protocols/http/detect-sqli.zeek` is loaded) Indicator of a URI based SQL injection attack. .. zeek:enum:: HTTP::POST_SQLI HTTP::Tags (present if :doc:`/scripts/policy/protocols/http/detect-sqli.zeek` is loaded) Indicator of client body based SQL injection attack. This is typically the body content of a POST request. Not implemented yet. .. zeek:enum:: HTTP::COOKIE_SQLI HTTP::Tags (present if :doc:`/scripts/policy/protocols/http/detect-sqli.zeek` is loaded) Indicator of a cookie based SQL injection attack. Not implemented yet. Indicate a type of attack or compromise in the record to be logged. Events ###### .. zeek:id:: HTTP::log_http :source-code: base/protocols/http/main.zeek 132 132 :Type: :zeek:type:`event` (rec: :zeek:type:`HTTP::Info`) Event that can be handled to access the HTTP record as it is sent on to the logging framework. Hooks ##### .. zeek:id:: HTTP::finalize_http :source-code: base/protocols/http/main.zeek 384 396 :Type: :zeek:type:`Conn::RemovalHook` HTTP finalization hook. Remaining HTTP info may get logged when it's called. .. zeek:id:: HTTP::log_policy :source-code: base/protocols/http/main.zeek 15 15 :Type: :zeek:type:`Log::PolicyHook`