Welcome to the New ClamAV Bytecode API Functions!

When writing signatures for the upcoming File Properties Collection Analysis feature, it is important to be aware of the various tools available for use. In this post, we will be covering the bytecode signature API specific to JSON manipulation of the collected property data structure. This is directed to signature writers. For information on writing bytecode signatures, refer to documentation in the clambc-compiler project, the walkthrough guide in the ClamAV project docs or other blog posts.

Determines if libclamav is configured with JSON.

    @return 0 - json is disabled or option not specified

    @return 1 - json is active and properties are available

int32_t json_is_active(void);

Retrieves the ID value of the specified named object within the specified parent object ID (object ID 0 is guaranteed to be defined as the topmost object).

    @return objid of json object with specified name
    @return 0 if json object of specified name cannot be found
    @return -1 if an error has occurred
    @param[in] name - name of object in ASCII
    @param[in] name_len - length of specified name (not including terminating NULL),
                          must be >= 0
    @param[in] objid - id value of json object to query
int32_t json_get_object(const int8_t* name, int32_t name_len, int32_t objid);

Determines the type of the specified JSON object, value is of the enumeration bc_json_type {JSON_TYPE_NULL=0, JSON_TYPE_BOOLEAN, JSON_TYPE_DOUBLE, JSON_TYPE_INT, JSON_TYPE_OBJECT, JSON_TYPE_ARRAY, JSON_TYPE_STRING}.

    @return type (json_type) of json object specified
    @return -1 if type unknown or invalid id
    @param[in] objid - id value of json object to query
int32_t json_get_type(int32_t objid);

Determines the length of the JSON array object; objid must be of type JSON_TYPE_ARRAY or an error will be returned.

    @return number of elements in the json array of objid
    @return -1 if an error has occurred
    @return -2 if object is not JSON_TYPE_ARRAY
    @param[in] objid - id value of json object (should be JSON_TYPE_ARRAY) to query

int32_t json_get_array_length(int32_t objid);

Retrieves the ID value for the object located at a specific index of a JSON array object; objid must be of type JSON_TYPE_ARRAY or an error will be returned.

    @return objid of json object at idx of json array of objid
    @return 0 if invalid idx
    @return -1 if an error has occurred
    @return -2 if object is not JSON_TYPE_ARRAY
    @param[in] idx - index of array to query, must be >= 0 and less than array length
    @param[in] objid - id value of json object (should be JSON_TYPE_ARRAY) to query
int32_t json_get_array_idx(int32_t idx, int32_t objid);

Determines the length of a JSON string object; objid must be of type JSON_TYPE_STRING or an error will be returned. Note: this value DOES NOT include the terminating null.

    @return length of json string of objid, not including terminating null-character
    @return -1 if an error has occurred
    @return -2 if object is not JSON_TYPE_STRING
    @param[in] objid - id value of json object (should be JSON_TYPE_STRING) to query
int32_t json_get_string_length(int32_t objid);

Retrieves the string contents of the JSON string object and stores it to a user location; objid must be of type JSON_TYPE_STRING or an error will be returned. Note: the specified length MUST include the terminating NULL.

    @return number of characters transferred (capped by str_len), 
            including terminating null-character
    @return -1 if an error has occurred
    @return -2 if object is not JSON_TYPE_STRING
    @param[out] str - user location to store string data; will be null-terminated
    @param[in] str_len - length of str or limit of string data to read,
                         including terminating null-character
    @param[in] objid - id value of json object (should be JSON_TYPE_STRING) to query
int32_t json_get_string(int8_t* str, int32_t str_len, int32_t objid);

Retrieves the boolean value of a JSON object.

    @return boolean value of queried objid; will force other types to boolean
    @param[in] objid - id value of json object to query
int32_t json_get_boolean(int32_t objid);

Retrieves the integer value of a JSON object.

    @return integer value of queried objid; will force other types to integer
    @param[in] objid - id value of json object to query
int32_t json_get_int(int32_t objid);

Note that since bytecode does not support double type, it is not possible to retrieve double values from JSON objects.