From: Jeff Lucovsky <jlucovsky@oisf.net>
Date: Fri, 25 Jul 2025 14:04:37 +0000 (-0400)
Subject: doc/fileinfo: Document fileinfo context/usage
X-Git-Tag: suricata-8.0.1~30
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=17e7387ff48a875d77e94bba98f5b7cc45e88ec1;p=thirdparty%2Fsuricata.git

doc/fileinfo: Document fileinfo context/usage

Issue: 6498
---

diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
index 13e8956f77..acba750fb7 100644
--- a/doc/userguide/output/eve/eve-json-format.rst
+++ b/doc/userguide/output/eve/eve-json-format.rst
@@ -614,6 +614,52 @@ Examples
       }
     }
 
+.. _eve-format-fileinfo:
+
+Event type: fileinfo
+--------------------
+
+Note that the checksum values for ``md5``, ``sha1``, and ``sha256`` are
+available when
+
+* The command line option ``disable-hashing`` was not used
+* There are no gaps (areas missing)
+
+Fields
+~~~~~~
+
+
+* "end: The offset of the last byte captured
+* "file_id": Integer value representing the id of a file that has been stored
+* "filename": Name of the file as observed in network traffic
+* "gaps": Boolean value indicating if there were gaps in the file
+* "magic": [optional, requires libmagic] The magic value for the file
+* "md5": Iff closed, md5 sum
+* "sha1": Iff closed, sha1 sum
+* "sha256": The sha256 value for the file, if available
+* "sid": One or more signature ids that triggered a `filestore`
+* "size": The observed size of the file, in bytes
+* "start": The offset of the first byte captured
+* "state": The state of the file when the record is written
+* "stored": Boolean value indicating whether the file has been stored
+* "storing": Boolean value indicating whether the file is in the process of being stored;
+  true when not yet stored
+* "tx_id": The transaction id in effect
+
+
+Offset values
+^^^^^^^^^^^^^
+
+This example shows the offset values from a ``fileinfo`` event -- note the ``http`` content
+range `start` and `end` value are replicated in the ``fileinfo`` fields::
+
+        http.content_range.raw: bytes 500-1000/146515
+        http.content_range.start: 500
+        http.content_range.end: 1000
+        http.content_range.size: 146515
+        fileinfo.start: 500
+        fileinfo.end: 1000
+
 .. _eve-format-http:
 
 Event type: HTTP
diff --git a/etc/schema.json b/etc/schema.json
index f3a7cd51fa..5024cd627d 100644
--- a/etc/schema.json
+++ b/etc/schema.json
@@ -1712,54 +1712,68 @@
             "additionalProperties": false,
             "properties": {
                 "end": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "The offset of the last byte captured"
                 },
                 "file_id": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Represents the id of a file that has been stored"
                 },
                 "filename": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Name of the file as observed in network traffic"
                 },
                 "gaps": {
-                    "type": "boolean"
+                    "type": "boolean",
+                    "description": "Indicates if there were gaps in the file"
                 },
                 "magic": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "[optional, requires libmagic] The magic value for the file"
                 },
                 "md5": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "[optional, if state is ``CLOSED``] When closed, md5 sum"
                 },
                 "sha1": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "[optional, if state is ``CLOSED]`` When closed, sha1 sum"
                 },
                 "sha256": {
-                    "type": "string"
+                    "type": "string",
+                    "description": " The sha256 value for the file, if available"
                 },
                 "sid": {
                     "type": "array",
                     "minItems": 1,
                     "items": {
-                        "type": "integer"
+                        "type": "integer",
+                        "description": "One or more signature ids that triggered a `filestore`"
                     }
                 },
                 "size": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "The observed size fo the file, in bytes"
                 },
                 "start": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "The offset of the first byte captured"
                 },
                 "state": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "The state of the file when the record is written"
                 },
                 "stored": {
-                    "type": "boolean"
+                    "type": "boolean",
+                    "description": "Indicates whether the file has been stored"
                 },
                 "storing": {
                     "type": "boolean",
-                    "description": "The file is set to be stored when completed"
+                    "description": "Indicates whether the file is in the process of being stored; true when not yet stored"
                 },
                 "tx_id": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "The transaction id in effect"
                 }
             }
         },