Generate docs (new tcp_options event)

Related to zeek/zeek#618
zeek · Oct 4, 2019 · df503b4 · df503b4
1 parent 218907b
commit df503b4
Show file tree

Hide file tree

Showing 8 changed files with 155 additions and 6 deletions.
diff --git a/script-reference/autogenerated-protocol-analyzer-index.rst b/script-reference/autogenerated-protocol-analyzer-index.rst
@@ -14804,6 +14804,51 @@ Components
 
 :zeek:enum:`Analyzer::ANALYZER_TCPSTATS`
 
+Types
++++++
+
+.. zeek:type:: TCP::Option
+
+   :Type: :zeek:type:`record`
+
+      kind: :zeek:type:`count`
+         The kind number associated with the option.  Other optional fields
+         of this record may be set depending on this value.
+
+      length: :zeek:type:`count`
+         The total length of the option in bytes, including the kind byte and
+         length byte (if present).
+
+      data: :zeek:type:`string` :zeek:attr:`&optional`
+         This field is set to the raw option bytes if the kind is not
+         otherwise known/parsed.  It's also set for known kinds whose length
+         was invalid.
+
+      mss: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 2: Maximum Segment Size.
+
+      window_scale: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 3: Window scale.
+
+      sack: :zeek:type:`index_vec` :zeek:attr:`&optional`
+         Kind 5: Selective ACKnowledgement (SACK).  This is a list of 2, 4,
+         6, or 8 numbers with each consecutive pair being a 32-bit
+         begin-pointer and 32-bit end pointer.
+
+      send_timestamp: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 8: 4-byte sender timestamp value.
+
+      echo_timestamp: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 8: 4-byte echo reply timestamp value.
+
+   A TCP Option field parsed from a TCP header.
+
+.. zeek:type:: TCP::OptionList
+
+   :Type: :zeek:type:`vector` of :zeek:type:`TCP::Option`
+
+   The full list of TCP Option fields parsed from a TCP header.
+
 Events
 ++++++
 
@@ -15130,9 +15175,27 @@ Events
 
    :optlen: The length of the options value.
 
-   .. zeek:see:: tcp_packet tcp_contents tcp_rexmit
+   .. zeek:see:: tcp_packet tcp_contents tcp_rexmit tcp_options
+
+   .. note:: To inspect the actual option values, if any, use :zeek:see:`tcp_options`.
+
+.. zeek:id:: tcp_options
+
+   :Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`, options: :zeek:type:`TCP::OptionList`)
+
+   Generated for each TCP header that contains TCP options.  This is a very
+   low-level event and potentially expensive as it may be raised very often.
+
+
+   :c: The connection the packet is part of.
+
+
+   :is_orig: True if the packet was sent by the connection's originator.
+
+
+   :options: The list of options parsed out of the TCP header.
 
-   .. note:: There is currently no way to get the actual option value, if any.
+   .. zeek:see:: tcp_packet tcp_contents tcp_rexmit tcp_option
 
 .. zeek:id:: tcp_contents
 

diff --git a/script-reference/autogenerated-script-index.rst b/script-reference/autogenerated-script-index.rst
@@ -149,6 +149,7 @@
    base/bif/plugins/Zeek_SteppingStone.events.bif.zeek </scripts/base/bif/plugins/Zeek_SteppingStone.events.bif.zeek>
    base/bif/plugins/Zeek_Syslog.events.bif.zeek </scripts/base/bif/plugins/Zeek_Syslog.events.bif.zeek>
    base/bif/plugins/Zeek_TCP.events.bif.zeek </scripts/base/bif/plugins/Zeek_TCP.events.bif.zeek>
+   base/bif/plugins/Zeek_TCP.types.bif.zeek </scripts/base/bif/plugins/Zeek_TCP.types.bif.zeek>
    base/bif/plugins/Zeek_TCP.functions.bif.zeek </scripts/base/bif/plugins/Zeek_TCP.functions.bif.zeek>
    base/bif/plugins/Zeek_Teredo.events.bif.zeek </scripts/base/bif/plugins/Zeek_Teredo.events.bif.zeek>
    base/bif/plugins/Zeek_UDP.events.bif.zeek </scripts/base/bif/plugins/Zeek_UDP.events.bif.zeek>

diff --git a/scripts/base/bif/index.rst b/scripts/base/bif/index.rst
@@ -400,6 +400,9 @@ Package: base/bif
 :doc:`/scripts/base/bif/plugins/Zeek_TCP.events.bif.zeek`
 
 
+:doc:`/scripts/base/bif/plugins/Zeek_TCP.types.bif.zeek`
+
+
 :doc:`/scripts/base/bif/plugins/Zeek_TCP.functions.bif.zeek`
 
 

diff --git a/scripts/base/bif/plugins/Zeek_TCP.events.bif.zeek.rst b/scripts/base/bif/plugins/Zeek_TCP.events.bif.zeek.rst
@@ -41,6 +41,7 @@ Events
 :zeek:id:`tcp_multiple_zero_windows`: :zeek:type:`event`    Generated if a TCP flow crosses a zero-window threshold, per
                                                             'W'/'w' history reporting.
 :zeek:id:`tcp_option`: :zeek:type:`event`                   Generated for each option found in a TCP header.
+:zeek:id:`tcp_options`: :zeek:type:`event`                  Generated for each TCP header that contains TCP options.
 :zeek:id:`tcp_packet`: :zeek:type:`event`                   Generated for every TCP packet.
 :zeek:id:`tcp_rexmit`: :zeek:type:`event`                   Generated for each detected TCP segment retransmission.
 =========================================================== =============================================================================
@@ -464,9 +465,27 @@ Events
 
    :optlen: The length of the options value.
 
-   .. zeek:see:: tcp_packet tcp_contents tcp_rexmit
+   .. zeek:see:: tcp_packet tcp_contents tcp_rexmit tcp_options
    
-   .. note:: There is currently no way to get the actual option value, if any.
+   .. note:: To inspect the actual option values, if any, use :zeek:see:`tcp_options`.
+
+.. zeek:id:: tcp_options
+
+   :Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`, options: :zeek:type:`TCP::OptionList`)
+
+   Generated for each TCP header that contains TCP options.  This is a very
+   low-level event and potentially expensive as it may be raised very often.
+
+
+   :c: The connection the packet is part of.
+
+
+   :is_orig: True if the packet was sent by the connection's originator.
+
+
+   :options: The list of options parsed out of the TCP header.
+
+   .. zeek:see:: tcp_packet tcp_contents tcp_rexmit tcp_option
 
 .. zeek:id:: tcp_packet
 

diff --git a/scripts/base/bif/plugins/Zeek_TCP.types.bif.zeek.rst b/scripts/base/bif/plugins/Zeek_TCP.types.bif.zeek.rst
@@ -0,0 +1,15 @@
+:tocdepth: 3
+
+base/bif/plugins/Zeek_TCP.types.bif.zeek
+========================================
+.. zeek:namespace:: GLOBAL
+
+
+:Namespace: GLOBAL
+
+Summary
+~~~~~~~
+
+Detailed Interface
+~~~~~~~~~~~~~~~~~~
+
diff --git a/scripts/base/bif/plugins/__load__.zeek.rst b/scripts/base/bif/plugins/__load__.zeek.rst
diff --git a/scripts/base/bif/plugins/index.rst b/scripts/base/bif/plugins/index.rst
@@ -292,6 +292,9 @@ Package: base/bif/plugins
 :doc:`/scripts/base/bif/plugins/Zeek_TCP.events.bif.zeek`
 
 
+:doc:`/scripts/base/bif/plugins/Zeek_TCP.types.bif.zeek`
+
+
 :doc:`/scripts/base/bif/plugins/Zeek_TCP.functions.bif.zeek`
 
 

diff --git a/scripts/base/init-bare.zeek.rst b/scripts/base/init-bare.zeek.rst
@@ -27,14 +27,15 @@ base/init-bare.zeek
 .. zeek:namespace:: SOCKS
 .. zeek:namespace:: SSH
 .. zeek:namespace:: SSL
+.. zeek:namespace:: TCP
 .. zeek:namespace:: Threading
 .. zeek:namespace:: Tunnel
 .. zeek:namespace:: Unified2
 .. zeek:namespace:: Weird
 .. zeek:namespace:: X509
 
 
-:Namespaces: BinPAC, Cluster, DCE_RPC, DHCP, GLOBAL, JSON, KRB, MOUNT3, MQTT, NCP, NFS3, NTLM, NTP, PE, Pcap, RADIUS, RDP, Reporter, SMB, SMB1, SMB2, SNMP, SOCKS, SSH, SSL, Threading, Tunnel, Unified2, Weird, X509
+:Namespaces: BinPAC, Cluster, DCE_RPC, DHCP, GLOBAL, JSON, KRB, MOUNT3, MQTT, NCP, NFS3, NTLM, NTP, PE, Pcap, RADIUS, RDP, Reporter, SMB, SMB1, SMB2, SNMP, SOCKS, SSH, SSL, TCP, Threading, Tunnel, Unified2, Weird, X509
 :Imports: :doc:`base/bif/const.bif.zeek </scripts/base/bif/const.bif.zeek>`, :doc:`base/bif/event.bif.zeek </scripts/base/bif/event.bif.zeek>`, :doc:`base/bif/option.bif.zeek </scripts/base/bif/option.bif.zeek>`, :doc:`base/bif/plugins/Zeek_KRB.types.bif.zeek </scripts/base/bif/plugins/Zeek_KRB.types.bif.zeek>`, :doc:`base/bif/plugins/Zeek_SNMP.types.bif.zeek </scripts/base/bif/plugins/Zeek_SNMP.types.bif.zeek>`, :doc:`base/bif/reporter.bif.zeek </scripts/base/bif/reporter.bif.zeek>`, :doc:`base/bif/stats.bif.zeek </scripts/base/bif/stats.bif.zeek>`, :doc:`base/bif/strings.bif.zeek </scripts/base/bif/strings.bif.zeek>`, :doc:`base/bif/types.bif.zeek </scripts/base/bif/types.bif.zeek>`, :doc:`base/bif/zeek.bif.zeek </scripts/base/bif/zeek.bif.zeek>`
 
 Summary
@@ -519,6 +520,8 @@ Types
 :zeek:type:`SSL::PSKIdentity`: :zeek:type:`record`                            
 :zeek:type:`SSL::SignatureAndHashAlgorithm`: :zeek:type:`record`              
 :zeek:type:`SYN_packet`: :zeek:type:`record`                                  Fields of a SYN packet.
+:zeek:type:`TCP::Option`: :zeek:type:`record`                                 A TCP Option field parsed from a TCP header.
+:zeek:type:`TCP::OptionList`: :zeek:type:`vector`                             The full list of TCP Option fields parsed from a TCP header.
 :zeek:type:`ThreadStats`: :zeek:type:`record`                                 Statistics about threads.
 :zeek:type:`TimerStats`: :zeek:type:`record`                                  Statistics of timers.
 :zeek:type:`Tunnel::EncapsulatingConn`: :zeek:type:`record` :zeek:attr:`&log` Records the identity of an encapsulating parent of a tunneled connection.
@@ -6538,6 +6541,48 @@ Types
 
    .. zeek:see:: connection_SYN_packet
 
+.. zeek:type:: TCP::Option
+
+   :Type: :zeek:type:`record`
+
+      kind: :zeek:type:`count`
+         The kind number associated with the option.  Other optional fields
+         of this record may be set depending on this value.
+
+      length: :zeek:type:`count`
+         The total length of the option in bytes, including the kind byte and
+         length byte (if present).
+
+      data: :zeek:type:`string` :zeek:attr:`&optional`
+         This field is set to the raw option bytes if the kind is not
+         otherwise known/parsed.  It's also set for known kinds whose length
+         was invalid.
+
+      mss: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 2: Maximum Segment Size.
+
+      window_scale: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 3: Window scale.
+
+      sack: :zeek:type:`index_vec` :zeek:attr:`&optional`
+         Kind 5: Selective ACKnowledgement (SACK).  This is a list of 2, 4,
+         6, or 8 numbers with each consecutive pair being a 32-bit
+         begin-pointer and 32-bit end pointer.
+
+      send_timestamp: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 8: 4-byte sender timestamp value.
+
+      echo_timestamp: :zeek:type:`count` :zeek:attr:`&optional`
+         Kind 8: 4-byte echo reply timestamp value.
+
+   A TCP Option field parsed from a TCP header.
+
+.. zeek:type:: TCP::OptionList
+
+   :Type: :zeek:type:`vector` of :zeek:type:`TCP::Option`
+
+   The full list of TCP Option fields parsed from a TCP header.
+
 .. zeek:type:: ThreadStats
 
    :Type: :zeek:type:`record`