Pull request #3607: appid : updating devnotes for first packet API

Merge in SNORT/snort3 from ~UMASHARM/snort3:dev_notes to master

Squashed commit of the following:

commit 2b7b7a40aca9ee785c048b5504d8e8c2bc30861e
Author: Umang Sharma <umasharm@cisco.com>
Date:   Thu Sep 29 13:34:23 2022 -0400

    appid : addressing review comments

commit ab17fa0aa9c94bc4b90db9ac2f2be08d488076c4
Author: Umang Sharma <umasharm@cisco.com>
Date:   Thu Sep 29 11:39:07 2022 -0400

    appid : addressing review comments

commit 1238c12482f1d8b1436193b648151286e3fa3b44
Author: Umang Sharma <umasharm@cisco.com>
Date:   Thu Sep 29 11:35:52 2022 -0400

    appid : addressing review comments

commit 6693b4f0513bd183356ea285996c9d83f8e8a12a
Author: Umang Sharma <umasharm@cisco.com>
Date:   Thu Sep 29 10:48:39 2022 -0400

    appid : addressing review comments

commit 189d356ca4cee29452306d300afc6af1fc129658
Author: Umang Sharma <umasharm@cisco.com>
Date:   Wed Sep 28 19:50:20 2022 -0400

    appid : updating devnotes for first packet API

diff --git a/src/network_inspectors/appid/dev_notes.txt b/src/network_inspectors/appid/dev_notes.txt
index 7b64cca790fdd83dcf20522f7402b1e5dd36e247..9972064116e7cbddd21abc7e6c7acaca9f21ddbe 100644 (file)
--- a/src/network_inspectors/appid/dev_notes.txt
+++ b/src/network_inspectors/appid/dev_notes.txt
@@ -142,3 +142,16 @@ the table corresponding to that detector is pulled from the Lua State and a call
 corresponding "validate" function in Lua code. The "validate" function in Lua can in turn make callbacks
 to C functions and shares its local stack with the C function. These functions make sure that the call
 is made only during discovery before executing.
+
+A custom first packet lua detector API which would map IP address, port and protocol on the very first packet to 
+application protocol (service appid), client application (client appid) and web application (payload appid). 
+This API is only used if a user creates a custom lua detector containing the IP, port, protocol values to be mapped to AppIDs.
+The first packet API shall offer performance improvements, reinspection and early detection of the traffic. 
+
+The values are stored in a cache during load time which are parsed in the lua detector API from the values passed
+through the custom detector lua file. During runtime, for every session, the first packet API is invoked, to find any cache entries 
+for the first packet. If there's an entry in the cache, the found appids are assigned accordingly, if no entries are found in the cache,
+further discovery is carried out on the incoming traffic.
+Here, there could be two scenarios, if the reinspection flag is enabled, discovery process is further continued and 
+appids found on first packet may or may not change, else if it is disabled, the discovery is stopped at the first packet itself 
+and appids remains the same for this entire session. 
\ No newline at end of file