Archived

This repository has been archived on 2025-09-14. You can view files and clone it, but cannot push or open issues or pull requests.

Files

root da715f21ef rename o2o and object2object to object_group

2024-10-24 07:56:49 +00:00

9.9 KiB

Raw Permalink Blame History

Getting started

Build

$ mkdir build && cd build
$ cmake ..
$ make
$ make install

Run test

$ cd build/test
$ ./maat_framework_gtest  #Functional test set
$ ./maat_framework_perf_gtest #Performance test set

Maat is used as a dynamic library by applications and its API is defined in the header file(maat.h).

Use case

A complete use case consists of three parts:

table schema: Define how to parse configuration in different types of tables, that is, specify what each column in the table represents.
configuration: Different types of configurations are stored in tables of the corresponding type.
maat_scan_xx/xx_plugin_get_ex_data: In the scanning scenario, the caller uses the maat_scan_xx api to determine whether the traffic hits effective rules; In the callback scenario, the caller uses the xx_plugin_get_ex_data api to query the ex_data of the specified key.

Case1

In the scanning scenario, it is necessary to configure the schema of multiple tables, including the item table, object2rule table, and rule table. If there is also object nesting involved, the schema of the object_group table needs to be configured.

(1) table schema

Table schema is stored in a json file(such as table_info.json), which is loaded when maat instance is created.

 [
    {
        "table_id":0,
        "table_name":"RULE",
        "table_type":"rule",
        "default_rule_table":0, /* key:indicate this is the default rule table, value:can be anything(not care) */
        "valid_column":8,
        "custom": {
            "rule_id":1,
            "tags":6,
            "condition_num":9
        }
    },
    {
        "table_id":1,
        "table_name":"OBJECT2RULE",
        "table_type":"object2rule",
        "associated_rule_table_id":0, /* associate rule table_id, object2rule table shares the same runtime with the corresponding rule table, so it needs to be mapped to the corresponding rule table. */
        "valid_column":3,
        "custom": {
            "object_id":1,
            "rule_id":2,
            "negate_option":4,
            "attribute_name":5,
            "condition_index":6
        }
    },
    {
        "table_id":2,
        "table_name":"OBJECT_GROUP",
        "table_type":"object_group",
        "valid_column":4,
        "custom": {
            "object_id":1,
            "included_sub_object_ids":2,
            "excluded_sub_object_ids":3
        }
    },
    {
        "table_id":3,
        "table_name":"HTTP_URL",
        "table_type":"expr",
        "valid_column":7,
        "custom": {
            "item_id":1,
            "object_id":2,
            "keywords":3,
            "expr_type":4,
            "match_method":5,
            "is_hexbin":6
        }
    }
 ]

(2) configuration

Configurations are stored in a json file(such as maat_json.json), which is loaded when maat instance is created.

{
    "rule_table": "RULE",
    "object2rule_table": "OBJECT2RULE",
    "object_group_table": "OBJECT_GROUP",
    "rules": [
        {
            "rule_id": 123,
            "service": 1,
            "action": 1,
            "do_blacklist": 1,
            "do_log": 1,
            "user_region": "anything",
            "is_valid": "yes",
            "objects": [
                {
                    "object_name": "Untitled",
                    "regions": [
                        {
                            "table_name": "HTTP_URL",
                            "table_type": "expr",
                            "table_content": {
                                "keywords": "Hello Maat",
                                "expr_type": "none",
                                "match_method": "sub",
                                "format": "uncase plain"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

(3) scanning

#include <assert.h>

#include "maat.h"

#define ARRAY_SIZE 16

const char *json_filename = "./maat_json.json";
const char *table_info_path = "./table_info.json";

int main()
{
    /* initialize maat options which will be used by maat_new() */
    struct maat_options *opts = maat_options_new();
    maat_options_set_json_file(opts, json_filename);
    maat_options_set_logger(opts, "./sample_test.log", LOG_LEVEL_INFO);

    /* create maat instance, rules in table_info.json will be loaded. */
    struct maat *maat_instance = maat_new(opts, table_info_path);
    assert(maat_instance != NULL);
    maat_options_free(opts);

    const char *table_name = "HTTP_URL"; /* maat_json.json has HTTP_URL rule */
    int table_id = maat_get_table_id(maat_instance, table_name);
    assert(table_id == 3); /* defined in table_info.json */

    int thread_id = 0;
    long long results[ARRAY_SIZE] = {0};
    size_t n_hit_result = 0;
    
    /* store scanning intermediate state */
    struct maat_state *state = maat_state_new(maat_instance, thread_id);
    assert(state != NULL);

    const char *scan_data = "Hello Maat, nice to meet you";

    /**
     * Becase maat instance has loaded rule in table_info.json which keywords is "Hello Maat",
       so maat_scan_string should return hit flag and rule's rule_id stored in results array.
    */
    int ret = maat_scan_string(maat_instance, table_id, scan_data, strlen(scan_data),
                               results, ARRAY_SIZE, &n_hit_result, state);
    assert(ret == MAAT_SCAN_HIT);
    assert(n_hit_result == 1);
    assert(results[0] == 123);

    maat_state_free(state);

    return 0;
}

Case2

In the callback scenario, only the schema of the corresponding table needs to be configured.