@@ -156,6 +156,14 @@ int onas_check_remote(struct onas_context  **ctx, cl_error_t *err) {

 	return ret;

 }

+/**

+ * @brief initialises a curl connection for the onaccess client; curl must be initialised globally before use

+ *

+ * @param curl pointer to the curl object to be used in the connection attempt

+ * @param ipaddr string which refers to either the TCPaddress or the local socket to connect to

+ * @param port the port to use in case of TCP connection, set to 0 if connecting to a local socket

+ * @param timeout time in ms to allow curl before timing out connection attempts

+ */

 CURLcode onas_curl_init(CURL **curl, const char *ipaddr, int64_t port, int64_t timeout) {

 	CURLcode curlcode = CURLE_OK;

@@ -382,6 +390,21 @@ int onas_get_clamd_version(struct onas_context **ctx)

     return 0;

 }

+/**

+ * @brief kick off scanning and return results

+ *

+ * @param tcpaddr   string string which refers to either the TCPaddress or the local socket to connect to

+ * @param portnum   the port to use in case of TCP connection, set to 0 if connecting to a local socket

+ * @param scantype  the type of scan to perform, e.g. fdpass, stream

+ * @param maxstream the max streamsize (in bytes) allowed across the socket per file

+ * @param fname     the name of the file to be scanned

+ * @param fd        the file descriptor for the file to be scanned, often (but not always) this is held by fanotify

+ * @param timeout   time in ms to allow curl before timing out connection attempts

+ * @param sb        variable to store and pass all of our stat info on the file so we don't have to access it multiple times (triggering multiple events)

+ * @param infected  return variable indincating whether daemon returned with an infected verdict or not

+ * @param err       return variable passed to the daemon protocol interface indicating how many things went wrong in the course of scanning

+ * @param ret_code  return variable passed to the daemon protocol interface indicating last known issue or success

+ */

 int onas_client_scan(const char *tcpaddr, int64_t portnum, int32_t scantype, uint64_t maxstream, const char *fname, int fd, int64_t timeout, STATBUF sb, int *infected, int *err, cl_error_t *ret_code)

 {

 	CURL *curl = NULL;

@@ -68,6 +68,28 @@ static struct onas_lnode *onas_listnode_init(void);

 static struct onas_hnode *onas_hashnode_init(void);

+/**

+ * The data structure described and implemented below is a hash table with elements that also act as relational nodes

+ * in a tree. This allows for average case constant time retrieval of nodes, and recursive operation on a node and all

+ * it's children and parents. The memory cost for this speed of relational retrieval is necessarily high, as every node

+ * must also keep track of it's children in a key-accessible way. To cut down on memory costs, children of nodes are not

+ * themselves key accessible, but must be combined with their parent in a constant-time operation to be retrieved from

+ * the table.

+ *

+ * Further optimization to retrieval and space management may include storing direct address to given children nodes, but

+ * such a design will create further complexitiy and time cost at insertion--which must also be as fast as possible in

+ * order to accomadate the real-time nature of security event processing.

+ *

+ * To date, the hashing function itself has not been well studied, and as such buckets were implemented from the start to

+ * help account for any potential collission issues in its design, as a measure to help offset any major time sinks during

+ * insertion.

+ *

+ * One last important note about this hash table is that to avoid massive slowdowns, it does not grow, but instead relies on

+ * buckets and a generous default size to distribute that load. Slight hit to retrieval time is a fair cost to pay to avoid

+ * total loss of service in a real-time system. Future work here might include automatically confiuguring initial hashtable

+ * size to align with the system being monitored, or max inotify watch points since that's our hard limit anyways.

+ */

+

 static inline uint32_t onas_hshift(uint32_t hash)

 {

@@ -84,6 +106,13 @@ static inline uint32_t onas_hshift(uint32_t hash)

     return hash;

 }

+/**

+ * @brief inline wrapper for onaccess inotify hashing function

+ *

+ * @param key       the string to be hashed

+ * @param keylen    size of the string

+ * @param size      the size of the hashtable

+ */

 static inline int onas_hash(const char *key, size_t keylen, uint32_t size)

 {

@@ -98,6 +127,9 @@ static inline int onas_hash(const char *key, size_t keylen, uint32_t size)

     return hash & (size - 1);

 }

+/**

+ * @brief initialises a bucketed hash table, pre-grown to the given size

+ */

 int onas_ht_init(struct onas_ht **ht, uint32_t size)

 {

@@ -177,7 +209,9 @@ static void onas_free_bucket(struct onas_bucket *bckt)

     return;

 }

-

+/**

+ * @brief the hash table uses buckets to store lists of key/value pairings

+ */

 struct onas_element *onas_element_init(struct onas_hnode *value, const char *key, size_t klen)

 {

@@ -258,7 +292,9 @@ static int onas_bucket_insert(struct onas_bucket *bckt, struct onas_element *ele

     return CL_SUCCESS;

 }

-/* Checks if key exists and optionally stores address to the element corresponding to the key within elem */

+/**

+ * @brief Checks if key exists and optionally stores address to the element corresponding to the key within elem

+ */

 int onas_ht_get(struct onas_ht *ht, const char *key, size_t klen, struct onas_element **elem)

 {

@@ -283,7 +319,9 @@ int onas_ht_get(struct onas_ht *ht, const char *key, size_t klen, struct onas_el

     return CL_SUCCESS;

 }

-/* Removes the element corresponding to key from the hashtable and optionally returns a pointer to the removed element. */

+/**

+ * @brief Removes the element corresponding to key from the hashtable and optionally returns a pointer to the removed element.

+ */

 int onas_ht_remove(struct onas_ht *ht, const char *key, size_t klen, struct onas_element **relem)

 {

     if (!ht || !key || klen <= 0) return CL_ENULLARG;

@@ -347,7 +385,9 @@ static int onas_bucket_remove(struct onas_bucket *bckt, struct onas_element *ele

 /* Dealing with hash nodes and list nodes */

-/* Function to initialize hashnode. */

+/**

+ * @brief Function to initialize hashnode, which is the data value we're storing in the hash table

+ */

 static struct onas_hnode *onas_hashnode_init(void)

 {

     struct onas_hnode *hnode = NULL;

@@ -381,7 +421,9 @@ static struct onas_hnode *onas_hashnode_init(void)

     return hnode;

 }

-/* Function to initialize listnode. */

+/**

+ * @brief Function to initialize listnodes, which ultimately allow us to traverse this datastructure like a tree

+ */

 static struct onas_lnode *onas_listnode_init(void)

 {

     struct onas_lnode *lnode = NULL;

@@ -397,7 +439,9 @@ static struct onas_lnode *onas_listnode_init(void)

     return lnode;

 }

-/* Function to free hashnode. */

+/**

+ * @brief Function to free hashnodes

+ */

 void onas_free_hashnode(struct onas_hnode *hnode)

 {

     if (!hnode) return;

@@ -416,7 +460,9 @@ void onas_free_hashnode(struct onas_hnode *hnode)

     return;

 }

-/* Function to free list of listnodes. */

+/**

+ * @brief Function to free list of listnode

+ */

 void onas_free_dirlist(struct onas_lnode *head)

 {

     if (!head) return;

@@ -432,7 +478,9 @@ void onas_free_dirlist(struct onas_lnode *head)

     return;

 }

-/* Function to free a listnode. */

+/**

+ * @brief Function to free a single listnode

+ */

 void onas_free_listnode(struct onas_lnode *lnode)

 {

     if (!lnode) return;

@@ -448,6 +496,9 @@ void onas_free_listnode(struct onas_lnode *lnode)

     return;

 }

+/**

+ * @brief Function to add a single value to a hashnode's listnode

+ */

 static int onas_add_hashnode_child(struct onas_hnode *node, const char *dirname)

 {

     if (!node || !dirname) return CL_ENULLARG;

@@ -463,7 +514,9 @@ static int onas_add_hashnode_child(struct onas_hnode *node, const char *dirname)

     return CL_SUCCESS;

 }

-/* Function to add a dir_listnode to a list */

+/**

+ * @brief Function to add a dir_listnode to a list

+ */

 int onas_add_listnode(struct onas_lnode *tail, struct onas_lnode *node)

 {

     if (!tail || !node) return CL_ENULLARG;

@@ -479,7 +532,9 @@ int onas_add_listnode(struct onas_lnode *tail, struct onas_lnode *node)

     return CL_SUCCESS;

 }

-/* Function to remove a listnode based on dirname. */

+/**

+ * @brief Function to remove a listnode based on dirname.

+ */

 int onas_rm_listnode(struct onas_lnode *head, const char *dirname)

 {

     if (!dirname || !head) return CL_ENULLARG;

@@ -505,7 +560,9 @@ int onas_rm_listnode(struct onas_lnode *head, const char *dirname)

 /*** Dealing with parent/child relationships in the table. ***/

-/* Determines parent and returns a copy based on full pathname. */

+/**

+ * @brief Determines parent of given directory and returns a copy based on full pathname.

+ */

 inline static char *onas_get_parent(const char *pathname, size_t len)

 {

     if (!pathname || len <= 1) return NULL;

@@ -530,7 +587,9 @@ inline static char *onas_get_parent(const char *pathname, size_t len)

     return ret;

 }

-/* Gets the index at which the name of directory begins from the full pathname. */

+/**

+ * @brief Gets the index at which the name of directory begins from the full pathname.

+ */

 inline static int onas_get_dirname_idx(const char *pathname, size_t len)

 {

     if (!pathname || len <= 1) return -1;

@@ -547,7 +606,15 @@ inline static int onas_get_dirname_idx(const char *pathname, size_t len)

     return idx;

 }

-/* Emancipates the specified child from the specified parent. */

+/**

+ * @brief Emancipates the specified child from the specified parent directory, typical done after a delete or move event

+ *

+ * @param ht        the hashtable structure

+ * @param prntpath  the full path of the parent director to be used hashed and used as a key to retrieve the corresponding entry from the table

+ * @param prntlen   the length of the parent path in bytes

+ * @param childpath the path of the child to be deassociated with the passed parent

+ * @param childlen  the length of the child path in bytes

+ */

 int onas_ht_rm_child(struct onas_ht *ht, const char *prntpath, size_t prntlen, const char *childpath, size_t childlen)

 {

@@ -569,7 +636,15 @@ int onas_ht_rm_child(struct onas_ht *ht, const char *prntpath, size_t prntlen, c

     return CL_SUCCESS;

 }

-/* The specified parent adds the specified child to its list. */

+/**

+ * @brief The specified parent adds the specified child to its list, typical done after a create, or move event

+ *

+ * @param ht        the hashtable structure

+ * @param prntpath  the full path of the parent director to be used hashed and used as a key to retrieve the corresponding entry from the table

+ * @param prntlen   the length of the parent path in bytes

+ * @param childpath the path of the child to be associated with the passed parent

+ * @param childlen  the length of the child path in bytes

+ */

 int onas_ht_add_child(struct onas_ht *ht, const char *prntpath, size_t prntlen, const char *childpath, size_t childlen)

 {

     if (!ht || !prntpath || prntlen <= 0 || !childpath || childlen <= 1) return CL_ENULLARG;

@@ -588,7 +663,9 @@ int onas_ht_add_child(struct onas_ht *ht, const char *prntpath, size_t prntlen,

 /*** Dealing with hierarchy changes. ***/

-/* Adds the hierarchy under pathname to the tree and allocates all necessary memory. */

+/**

+ * @brief Adds the hierarchy under pathname to the tree and allocates all necessary memory.

+ */

 int onas_ht_add_hierarchy(struct onas_ht *ht, const char *pathname)

 {

     if (!ht || !pathname) return CL_ENULLARG;

@@ -674,7 +751,9 @@ out:

     return CL_SUCCESS;

 }

-/* Removes the underlying hierarchy from the tree and frees all associated memory. */

+/**

+ * @brief Removes the underlying hierarchy from the tree and frees all associated memory.

+ */

 int onas_ht_rm_hierarchy(struct onas_ht *ht, const char *pathname, size_t len, int level)

 {

     if (!ht || !pathname || len <= 0) return CL_ENULLARG;

@@ -92,6 +92,9 @@ static int onas_ddd_init_ht(uint32_t ht_size)

     return onas_ht_init(&ddd_ht, ht_size);

 }

+/**

+ * @brief Initialize watch descriptor lookup table which we use alongside inotify to keep track of which open watchpoints correspond to which objects

+ */

 static int onas_ddd_init_wdlt(uint64_t nwatches)

 {

@@ -105,6 +108,9 @@ static int onas_ddd_init_wdlt(uint64_t nwatches)

     return CL_SUCCESS;

 }

+/**

+ * @brief Initialize watch descriptor lookup table which we use alongside inotify to keep track of which open watchpoints correspond to which objects

+ */

 static int onas_ddd_grow_wdlt()

 {

@@ -152,6 +158,9 @@ int onas_ddd_init(uint64_t nwatches, size_t ht_size)

     return CL_SUCCESS;

 }

+/**

+ * @brief convenience function for adding both inotify and fanotify watchpoints for a single path in one go

+ */

 static int onas_ddd_watch(const char *pathname, int fan_fd, uint64_t fan_mask, int in_fd, uint64_t in_mask)

 {

     if (!pathname || fan_fd <= 0 || in_fd <= 0) return CL_ENULLARG;

@@ -168,6 +177,15 @@ static int onas_ddd_watch(const char *pathname, int fan_fd, uint64_t fan_mask, i

     return CL_SUCCESS;

 }

+/**

+ * @brief recursively adds a hierarchy from the hash table and all watches of a single type to specified object

+ *

+ * @param pathname  the directory to start watching

+ * @param len       the size of pathname in bytes

+ * @param fd        the fanotify or inotify file descriptor

+ * @param mask      options for watching the path

+ * @param type      specifies whether or not to add inotify or fanotify watchpoints and the type of fd passed

+ */

 static int onas_ddd_watch_hierarchy(const char *pathname, size_t len, int fd, uint64_t mask, uint32_t type)

 {

@@ -204,6 +222,7 @@ static int onas_ddd_watch_hierarchy(const char *pathname, size_t len, int fd, ui

         return CL_EARG;

     }

+    /* recursively watch all children */

     struct onas_lnode *curr = hnode->childhead;

     while (curr->next != hnode->childtail) {

@@ -227,6 +246,9 @@ static int onas_ddd_watch_hierarchy(const char *pathname, size_t len, int fd, ui

     return CL_SUCCESS;

 }

+/**

+ * @brief convenience function for removing both inotify and fanotify watchpoints for a single path in one go

+ */

 static int onas_ddd_unwatch(const char *pathname, int fan_fd, int in_fd)

 {

     if (!pathname || fan_fd <= 0 || in_fd <= 0) return CL_ENULLARG;

@@ -243,6 +265,14 @@ static int onas_ddd_unwatch(const char *pathname, int fan_fd, int in_fd)

     return CL_SUCCESS;

 }

+/**

+ * @brief recursively removes a hierarchy from the hash table and drops all watches of a single type from linked objects

+ *

+ * @param pathname  the directory to stop watching

+ * @param len       the size of pathname in bytes

+ * @param fd        the fanotify or inotify file descriptor

+ * @param type      specifies whether or not to remove inotify or fanotify watchpoints and the type of fd passed

+ */

 static int onas_ddd_unwatch_hierarchy(const char *pathname, size_t len, int fd, uint32_t type)

 {

@@ -275,6 +305,7 @@ static int onas_ddd_unwatch_hierarchy(const char *pathname, size_t len, int fd,

         return CL_EARG;

     }

+    /* free all children recursively */

     struct onas_lnode *curr = hnode->childhead;

     while (curr->next != hnode->childtail) {

@@ -63,13 +63,14 @@ static void onas_scan_thread_exit(int sig)

 }

 /**

- * Safe-scan wrapper, originally used by inotify and fanotify threads, now exists for error checking/convenience.

- * Owned by scanthread to force multithreaded client archtiecture which better avoids kernel level deadlocks from

- * fanotify blocking/prevention

+ * @brief Safe-scan wrapper, originally used by inotify and fanotify threads, now exists for error checking/convenience.

+ *

+ * Owned by scanthread to try and force multithreaded client archtiecture which better avoids kernel level deadlocks from

+ * fanotify blocking/prevention.

  */

 static int onas_scan(struct onas_scan_event *event_data, const char *fname, STATBUF sb, int *infected, int *err, cl_error_t *ret_code)

 {

-    int ret             = 0;

+    int ret = 0;

     int i = 0;

     uint8_t retry_on_error = event_data->bool_opts & ONAS_SCTH_B_RETRY_ON_E;

@@ -108,7 +109,11 @@ static int onas_scan(struct onas_scan_event *event_data, const char *fname, STAT

 }

 /**

- * Thread-safe scan wrapper to ensure there's no processs contention over use of the socket.

+ * @brief Thread-safe scan wrapper to ensure there's no processs contention over use of the socket.

+ *

+ * This is noticeably slower, and I had no issues running smaller scale tests with it off, but better than sorry until more testing can be done.

+ *

+ * TODO: make this configurable?

  */

 static cl_error_t onas_scan_safe(struct onas_scan_event *event_data, const char *fname, STATBUF sb, int *infected, int *err, cl_error_t *ret_code) {

@@ -300,6 +305,11 @@ static cl_error_t onas_scan_thread_handle_file(struct onas_scan_event *event_dat

 	return ret;

 }

+/**

+ * @brief worker thread designed to work with the lovely c-thread-pool library to handle our scanning jobs after our queue thread consumes an event

+ *

+ * @param arg this should always be an onas_scan_event struct

+ */

 void *onas_scan_worker(void *arg) {

 	struct onas_scan_event *event_data = (struct onas_scan_event *) arg;

@@ -374,8 +384,16 @@ done:

 	return NULL;

 }

-/* Simple utility function for external interfaces to add relevant context information to scan_event struct;

- * doing this mapping cuts down significantly on memory overhead when queueing hundreds of these scan_event structs */

+/**

+ * @brief Simple utility function for external interfaces to add relevant context information to scan_event struct.

+ *

+ * Doing this mapping cuts down significantly on memory overhead when queueing hundreds of these scan_event structs

+ * especially vs using a copy of a raw context struct.

+ *

+ * Other potential design options include giving the event access to the "global" context struct address instead,

+ * to further cut down on space used, but (among other thread safety concerns) I'd prefer the worker threads not

+ * have the ability to modify it at all to keep down on potential maintenance headaches in the future.

+ */

 cl_error_t onas_map_context_info_to_event_data(struct onas_context *ctx, struct onas_scan_event **event_data) {

     if(NULL == ctx || NULL == event_data || NULL == *event_data) {