5. REST API Documentation

The HAWK REST API v1.1 allows users to dynamically pull custom data per the customer’s requirements. The REST API lives at the /API/1.1/ endpoint and responds to GET, POST, OPTIONS, PUT, and DELETE. You will need to authenticate in order to use the API.

Warning

Using the API directly could result in damaging your data if not done correctly. API documentation should only be used as a reference guide. It is highly recommend that you use the HAWK eyeCon portal to interact with your data.

5.1. Request and Response headers

GET /API/1.1/generic

These are generic request and response headers.

Request Headers

• Host – Specifies the Internet host and port number of the resource being requested, as obtained from the original URI given by the user or referring resource.

• User-Agent – Contains information about the user agent originating the request. Any user agent is accepted.

• Accept – Specify certain media types which are acceptable for the response

• Accept-Language – Similar to Accept, but restricts the set of natural languages that are preferred as a response to the request. (i.e. en-US,en;q=0.5 )

• Accept-Encoding – Similar to Accept, but restricts the content-codings that are acceptable in the response. (i.e. gzip, deflate )

• HAWK-IEK – HAWK version 4.2-af8bf

• Content-Type – Indicates the media type of the entity-body sent to the recipient (i.e. application/x-www-form-urlencoded; charset=UTF-8 )

• Referer – Allows the client to specify, the address (URI) of the resource from which the Request-URI was obtained

• Content-Length – Indicates the size of the entity-body.

• Cookie – HSID=<HAWK Session ID> address=<Security HASH>; username=<User name hash>; HS=<Top Group for User>

• Connection – Allows the sender to specify options that are desired for that particular connection. (i.e. keep-alive )

• Pragma – Directives to specify optional behaviour from the viewpoint of the protocol. (i.e. no-cache)

• Cache-Control – Is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain (i.e. no-cache )

Response Headers

• Date – General-header field represents the date and time at which the message was originated

• Content-Type – Depends on request header Accept and Content-Type

• Connection – Allows the sender to specify options that are desired for that particular connection. (i.e. keep-alive )

• Vary – Indicates the set of request-header fields that fully determines, while the response is fresh, whether a cache is permitted to use the response to reply to a subsequent request without revalidation. (i.e. Accept-Encoding )

• X-Powered-By – PHP version (i.e. PHP/5.3.3 )

• Cache-Control – Is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain (i.e. private, max-age=600, pre-check=600)

• Last-Modified – Indicates the date and time at which the origin server believes the variant was last modified

• Set-Cookie – Set or modify Cookie. (i.e. HS=.; path=/; expires=Mon, 30-Jun-2014 16:37:15 UTC)

• Access-Control-Allow-Methods – Specifies the method or methods allowed when accessing the resource. (i.e. GET, POST, OPTIONS, PUT, DELETE)

• Access-Control-Allow-Credentials – Indicates whether or not the response to the request can be exposed when the credentials flag is true

• Access-Control-Expose-Headers – This lets a server whitelist headers that browsers are allowed to access. (i.e. HAWK-IEK,HAWK-Status,X-HAWK-Request,content-type)

• Access-Control-Request-Method – Used when issuing a preflight request to let the server know what HTTP method will be used when the actual request is made. (i.e. * )

• Access-Control-Request-Headers – Used when issuing a preflight request to let the server know what HTTP headers will be used when the actual request is made. (i.e. * )

• Access-Control-Allow-Headers – Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. (i.e. HAWK-IEK,Origin,Authorization,Content-Type,Accept,User-Agent,DNT,Cache-Control,X-Mx-ReqToken,Keep-Alive,X-Requested-With,If-Modified-Since,X-XSRF-Token )

• Expires – Gives the date/time after which the response is considered stale.

• X-HAWKCache – Tells the API to ignore cache or not. 0 = don’t ignore, 1 = ignore

• HAWK-Parent-Group – HAWK group.

• HSID – HAWK Session ID.

• X-Cached – MISS or HIT - If the response is from cache or not from cache.

• X-HAWKCache-Ignore – 0 or 1 - 0 = Do not ignore cache. 1 = Ignore cache.

• Content-Length – Indicates the size of the entity-body.

5.2. Scores

GET /API/1.1/scores-classification

Gets a list of correlation rules action categories. List includes: search_category_id, search_category_name, search_category_details, and sort.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

GET /API/1.1/scores

Returns an array of all score rules for selected group and/or group and sub-groups. List includes: filter_id, filter_name, correlation_action, actions_category_name, correlation_rules_id, group_name, and rules[id, key, value, compare, optiional].

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• group (string) – Group Name.

• recursive (boolean) – true or false

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – success

Error Response:

Status Codes

• 500 Internal Server Error – Exception, Displays error message.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

PUT /API/1.1/scores

Create new score.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• filter_name – Name for filter.

• actions_category_name – Add (+) or Subtract (-)

• correlation_action – Amount that should be added or subtracted.

• group_name – Group name.

• rules[0][key] – See Key Comparisons table in reference guide.

• rules[0][compare] – lte = Less Than or Equal To, lt = Less Than, equals = Equal to, not = Not Equal, gt = Greater Than, gte = Greater Than or Equal To.

• rules[0][value] – What you are comparing the key to.

• rules[0][threshold] – Threshold count.

• rules[0][min_severity] – Minimum severity.

• rules[0][actions_category_name] – See actions category name in reference guide.

• rules[0][actions_category_value] – See actions category value in reference guide.

• rules[0][count_value] – Count for key count items.

• rules[0][actions_count_category_value] – Count for key count items.

• rules[0][alert_name] – Value to compare for key alert name items.

• rules[0][actions_auction_name] – Actions auction name.

• rules[0][cat_threshold] – Alert category threshold.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

DELETE /API/1.1/scores/(int : id)

Removes score based on unique ID.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• id (int) – Unique score id.

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception:Displays error message.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

POST /API/1.1/scores

Update scores.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• filter_name – Name for filter.

• actions_category_name – Add (+) or Subtract (-)

• correlation_action – Amount that should be added or subtracted.

• group_name – Group name.

• rules[0][key] – See Key Comparisons table in reference guide.

• rules[0][compare] – lte = Less Than or Equal To, lt = Less Than, equals = Equal to, not = Not Equal, gt = Greater Than, gte = Greater Than or Equal To.

• rules[0][value] – What you are comparing the key to.

• rules[0][threshold] – Threshold count.

• rules[0][min_severity] – Minimum severity.

• rules[0][actions_category_name] – See actions category name in reference guide.

• rules[0][actions_category_value] – See actions category value in reference guide.

• rules[0][count_value] – Count for key count items.

• rules[0][actions_count_category_value] – Count for key count items.

• rules[0][alert_name] – Value to compare for key alert name items.

• rules[0][actions_auction_name] – Actions auction name.

• rules[0][cat_threshold] – Alert category threshold.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

5.3. Authentication

GET /API/1.1/pre-fetch

Pre-fetch will create our users session’s nonce key.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None

Data Parameters

None

Success Response:

None

Error Response:

None

GET /API/1.1/login

Session authentication handler and error message output.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Failure invalid request.

POST /API/1.1/login

Authentication and session creation.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• username – Username

• password – sha1(password) or clear text password if secure is not set.

• secure – nonce, true, empty

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 401 Unauthorized – Failure.

• 401 Unauthorized – Failure, Invalid username or password supplied.

• 401 Unauthorized – Failure, Invalid parameters, Please verify your request.

• 401 Unauthorized – Failure, We are unable to complete your login, Your account has been locked. Please contact your administrator to continue.

GET /API/1.1/logout

Logs user out and removes session headers.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

None

GET /API/1.1/forgot-password/(string : email)

Forgot password handler function. Resets users password to temparary password.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• email (string) – E-mail address

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 401 Unauthorized – Failure.

• 400 Bad Request – Unable to complete password reset, more than one account has been associated with this e-mail address.

• 400 Bad Request – Unable to complete password reset, invalid e-mail address.

5.4. Incidents

POST /API/1.1/search/incidents

Search incidents.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order columns separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

• records – Empty

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Unable to process request, no column parameters specified.

• 400 Bad Request – Unable to process request, exception:

POST /API/1.1/incident/(hash : id)/status

Update current status of incident by specified incident ID.

Access Control Requirements

Event Manager.

URL Parameters

Required:

Parameters

• id (hash) – Unique incident id hash.

Optional:

None

Data Parameters

Form Parameters

• status – Possible status: new, open, in progress, pending, false positive, closed

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Invalid status provided.

• 400 Bad Request – Invalid incident results.

• 400 Bad Request – Unable to process request, exception:

PUT /API/1.1/incident/(hash : id)/notes

Add notes to incident by incident hash ID. The following are automaticly created: date_added, username, and fullname.

Access Control Requirements

Event Manager.

URL Parameters

Required:

Parameters

• id (hash) – Unique incident id number.

Optional:

None

Data Parameters

Form Parameters

• message – Note for specified incident.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Invalid incident results.

• 400 Bad Request – Unable to process request, exception:

5.5. Audit/Compliance

POST /API/1.1/search/audit

Search audits.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order columns separated by a comma. DESC = Descending and ASC = Ascending (default date_added DESC)

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Unable to process request, No column parameters specified.

• 400 Bad Request – Exception, Unable to process request.

5.6. Resources

DELETE /API/1.1/resource/(int : id)

Delete resouce by id.

Access Control Requirements

Moderator.

URL Parameters

Required:

Parameters

• id (int) – Unique incident id.

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

POST /API/1.1/search/resource

Search for a resource.

Access Control Requirements

Moderator.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order columns separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

GET /API/1.1/resource-pulse/templates

Returns a json file containing all the resource pluse templaes.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

None

GET /API/1.1/resource-pulse/lock/(int : id)/template/(int : template_id)

Update record and unlock

Access Control Requirements

Moderator.

URL Parameters

Required:

Parameters

• id (int) – Unique resource id.

• template_id (int) – Unique template id.

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

• 200 OK – Resource locked successfully.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Resource pulse template is currently locked for ongoing minutes minutes

• 400 Bad Request – Resource unable to be locked successfully.

• 400 Bad Request – More than one record found to match this request :id.

• 400 Bad Request – No record was found to match this request :id.

• 500 Internal Server Error – Exception details

GET /API/1.1/resource-pulse/unlock/(type: id)/template/(type: template_id)

Update record and unlock

Access Control Requirements

Moderator.

URL Parameters

Required:

Parameters

• id (type) – Unique resource id.

• template_id (type) – Unique template id.

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

• 200 OK – Resource unlocked successfully.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – No pulse templates available within record.

• 400 Bad Request – Resource unable to be unlocked successfully.

• 400 Bad Request – More than one record found to match this request :id.

• 400 Bad Request – No record was found to match this request :id.

• 500 Internal Server Error – Exception details

POST /API/1.1/resource/(hash : id)

Update resource by resource hash id.

Access Control Requirements

Moderator.

URL Parameters

Required:

Parameters

• id (hash) – Unique resource id.

Optional:

None.

Data Parameters

Form Parameters

• resource_address – IPv4 address.

• resource_address6 – IPv6 address.

• resource_details – Notes for resource.

• resource_name – Name given to resource.

• os_type_name – From list see resource-classification.

• os_type_details – From list see resource-classification.

• class_type – From list see resource-classification.

• class_name – From list see resource-classification.

• boolean complianceasset – Is this resource a compliance Asset? True or False

• Asset Criticality – Asset criticality 1 to 5.

• date_added – Timestamp (i.e. 2014-06-17 13:14:23.635000 )

• resource_id – resource hash id.

• last_seen – Timestamp (i.e. 1970-01-01 00:00:00 )

Success Response:

Status Codes

• 200 OK – Success.

• 200 OK – Resource unlocked successfully.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

PUT /API/1.1/resource

Add a resource.

Access Control Requirements

Moderator.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• resource_address – IPv4 address.

• resource_address6 – IPv6 address. (May be empty.)

• resource_name – Name given to resource.

• resource_details – Notes for resource.

• os_type_name – From list see resource-classification.

• os_type_details – From list see resource-classification.

• class_type – From list see resource-classification.

• class_name – From list see resource-classification.

• boolean complianceasset – Is this resource a compliance Asset? True or False

• Asset Criticality – Asset criticality 1 to 5.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Unable to update last_seen record.

GET /API/1.1/resource-classification

Returns a list of all resource classifications. List includes: os_type_name, os_type_details, os_type_key, class_type, and class_name.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None

Data Parameters

None

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 500 Internal Server Error – Failure.

5.7. Events

PUT /API/1.1/events

Create a new event

Access Control Requirements

Moderator.

URL Parameters

Required:

None

Optional:

None

Data Parameters

JSON data using short hand column names.

{
            "g_n":"default-group",
            "s_g_n":"United States",
            "hash":"5B7AD672D7098ECDD879AAB9D9ACD00D",
            "o_name":"McAfee Intrusion Detection System",
            "r_addr":"19.148.129.112",
            "w":8.0,
            "r_addr6":"",
            "s_g_cc2":"US",
            "ip_dport":514,
            "s_g_c":"Dallas",
            "date":"2014-06-17 19:46:25",
            "r_name":"dalinternet-3a",
            "ts":1403034385,
            "c_key":"IDS",
            "hid":"HID3019",
            "rs_v":"+ 1.50, + 1.50, + 3.50, + 1.50, ",
            "at_name":"Scanning/Recon",
            "a_name":"TCP: SYN Port Scan",
            "ip_sport":0,
            "pri":3,
            "s_g_la":32.643100128173828,
            "s_g_r":"TX",
            "s_g_lo":-96.50670166015625,
            "ip_sh":"69.243.120.111",
            "ip_s":"69.243.120.111",
            "ip_s6":"",
            "ip_dh":"10.30.184.165",
            "ip_proto":6,
            "ip_d":"10.30.184.165",
            "ip_d6":"",
            "rs_n":"Alert Threshold Count 100 Events (15 Minute), Alert Threshold Count 10 Events (5 Minute), Bayesian Signature (Extremely High), Priority 3, ",
            "payload":"<188>Jun 17 14:46:26 SyslogAlertForwarder: |5012789840344498544|Port Scan|2014-04-17 14:46:23 CDT|\"TCP: SYN Port Scan\"|0x40008500|Medium|N/A|Low|Default-Group ITO|DALINTERNET|3A|69.243.120.111|0|10.30.184.165|N/A|Reconnaissance|port-scan|Unknown|n/a|threshold|N/A|N/A|"

    }

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

POST /API/1.1/search/events

Search existing events for given time period. Returns json data.

Access Control Requirements

Event Manager.

URL Parameters

Required:

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order colums separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• begin – Timestamp. (i.e. 2014-06-17 12:15:00 )

• end – Timestamp. (i.e. 2014-06-17 12:20:00 )

Optional:

Form Parameters

• limit –

• column[] –

• where[] –

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Failure, Invalid request.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

• 500 Internal Server Error – Begin date provided appears to be in the future, or invalid.

• 500 Internal Server Error – End date provided appears to be in the future, or invalid.

5.8. Vulnerabilities

PUT /API/1.1/vulnerabilities

Add vulnerability result(s).

Access Control Requirements

Moderator.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

json data

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

POST /API/1.1/search/vulnerabilities

Search existing vulnerabilities for given time period. Returns json data.

Access Control Requirements

Event Manager.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order columns separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

• begin – Timestamp. (i.e. 2014-06-17 12:15:00 )

• end – Timestamp. (i.e. 2014-06-17 12:20:00 )

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Failure, Invalid request.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

• 500 Internal Server Error – Begin date provided appears to be in the future, or invalid.

• 500 Internal Server Error – End date provided appears to be in the future, or invalid.

5.9. Users

DELETE /API/1.1/users/(int : id)

Delete existing user by user id.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• id (int) – Unique user id

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

PUT /API/1.1/users

Create a new user.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• username – Username

• fullname – Full name.

• email – E-mail address.

• group_name – Parent group for user.

• phone – Primary phone number.

• phone2 – Secondary phone number. May be empty.

• boolean account_lock – 0 = False 1 = True

• boolean email_recipient – true or false

• signature – E-mail signature.

• boolean admin – true or false

• boolean moderator – true or false

• boolean sysop – true or false

• boolean audit – true or false

• boolean event_manager – true or false

• boolean reports – true or false

• password – Clear text password for user.

• password2 – Repeat password.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Invalid field username.

• 400 Bad Request – Invalid field password.

• 400 Bad Request – Invalid field password2.

• 400 Bad Request – Invalid field fullname.

• 400 Bad Request – Invalid field email.

POST /API/1.1/users/(int : id)

Update existing user. You can not change a username. You have to delete the user and re-create the user if you want to change the username.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• id (int) – Unique user id

Optional:

None.

Data Parameters

Form Parameters

• uid – Unique user id.

• username – Username

• fullname – Full name.

• email – E-mail address.

• group_name – Parent group for user.

• phone – Primary phone number.

• phone2 – Secondary phone number. May be empty.

• boolean account_lock – 0 = False 1 = True

• boolean email_recipient – true or false

• signature – E-mail signature.

• boolean admin – true or false

• boolean moderator – true or false

• boolean sysop – true or false

• boolean audit – true or false

• boolean event_manager – true or false

• boolean reports – true or false

• password – Clear text password for user.

• password2 – Repeat password.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Invalid field username.

• 400 Bad Request – Invalid field password.

• 400 Bad Request – Invalid field password2.

• 400 Bad Request – Invalid field fullname.

• 400 Bad Request – Invalid field email.

POST /API/1.1/search/users

Search for existing users.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order columns separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Unable to process request, exception.

POST /API/1.1/users-settings

Update existing user. You can not change a username. You have to delete the user and re-create the user if you want to change the username.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• id (int) – Unique user id

Optional:

None.

Data Parameters

Form Parameters

• uid – Unique User ID.

• username – Username

• fullname – Full name.

• email – E-mail address.

• phone – Primary phone number.

• phone2 – Secondary phone number. May be empty.

• signature – E-mail signature.

• password – Clear text password for user. (Only if you want to change the password.)

• password2 – Repeat password. (Only if you want to change the password.)

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Exception.

5.10. Groups

DELETE /API/1.1/group/(string: name)

Deletes specified group.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• name (string) – Name of group

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception

GET /API/1.1/group

Returns list of proprites for specifed group or groups. List includes: id, name, key, parent, test, details, date_modified, and children.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

Query Parameters

• name (string) – Group name.

• recursive (boolean) – true or false. Default true.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 504 Gateway Timeout – Invalid results.

PUT /API/1.1/group

Add new group.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• name – Name of new group.

• details – Detail description of group. May be empty.

• shard – Shard group is associated to. May be empty.

• parent – Parent group new group belongs to.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Invalid field name.

• 400 Bad Request – Invalid field details.

• 400 Bad Request – Invalid field parent.

• 504 Gateway Timeout – Invalid results.

POST /API/1.1/group/(int: id)

Update existing group by group id.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• id (int) – Group unique id.

Optional:

None.

Data Parameters

Form Parameters

• name – Name of new group.

• details – Detail description of group. May be empty.

• group_id – Group id.

• parent – Parent group new group belongs to.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Invalid field name.

• 400 Bad Request – Invalid field details.

• 400 Bad Request – Invalid field parent.

• 400 Bad Request – Exception

5.11. Dashboards and Widgets

GET /API/1.1/dashboards/(int : template_id)/widgets

Returns list of widgets for specified template id. List includes: widget_id, widget_name, widget_details, output_type[type, label, value, rotate, data_type, width], column_params[], where_params[], groupby_params[], orderby_params[], limit_params, dashbaord_id, widget_sort, dashbaord_height, dashbaord_width, height, and width.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – Unique template id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

PUT /API/1.1/dashboards/templates/(int : template_id)/widgets

Add new dashboard template widget.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id – Template unique id.

Optional:

None.

Data Parameters

Form Parameters

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• widget_name – Widget name.

• widget_details – Widget details

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• template_base_id – Template prefix id.

• boolean saveAsTemplate – true or false.

• widget_category_id – Widget category id.

• dashboard_widget_name – Dashboard widget name.

• dashboard_details – Details for dashboard widget.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

POST /API/1.1/dashboards/templates/widget/(int : widget_id)

Update existing dashboard template widget.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• widget_id – Widget unique id.

Optional:

None.

Data Parameters

Form Parameters

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• widget_name – Widget name.

• widget_details – Widget details

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• template_base_id – Template prefix id.

• boolean saveAsTemplate – true or false.

• widget_category_id – Widget category id.

• dashboard_widget_name – Dashboard widget name.

• dashboard_details – Details for dashboard widget.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards widgets found for specified widget id.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/dashboards/templates/widget/(int : widget_id)

Delete existing dashboard template widget.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• widget_id (int) – Unique widget id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards template widget found.

• 500 Internal Server Error – Exception.

PUT /API/1.1/dashboards/templates

Add new dashboard template.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• dashboard_id – Dashboard unique id.

• dashboard_name – Dashboard template name.

• dashboard_details – Dashboard template details.

• boolean dashboard_group – 0 or 1

• boolean dashboard_type – 0 or 1 (1 = Filter, 0 = Associative )

• boolean dashboard_sort – 0 or 1

• dashboard_user – Dashboard user id.

• boolean dashboard_private – 0 or 1

• group_name – Group name.

• boolean isSelected – true or false.

• template_base_id – Template prefix id. Can be empty.

• boolean saveAsTemplate – true or false.

• category – Template category.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards template widget found.

• 500 Internal Server Error – Exception.

POST /API/1.1/dashboards/templates/(int : template_id)

Update existing dashboard template.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – Template unique id.

Optional:

None.

Data Parameters

Form Parameters

• template_id – Template unique id.

• dashboard_id – Dashboard unique id.

• dashboard_name – Dashboard template name.

• dashboard_details – Dashboard template details.

• boolean dashboard_group – 0 or 1

• boolean dashboard_type – 0 or 1 (1 = Filter, 0 = Associative )

• boolean dashboard_sort – 0 or 1

• dashboard_user – Dashboard user id.

• boolean dashboard_private – 0 or 1

• group_name – Group name.

• boolean isSelected – true or false.

• template_base_id – Template prefix id. Can be empty.

• boolean saveAsTemplate – true or false.

• category – Template category.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards template widget found.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/dashboards/templates/(int : template_id)

Delete existing dashboard template.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – Template unique id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards found for specified username.

• 500 Internal Server Error – Exception.

GET /API/1.1/dashboards/categories

Returns a list of dashboard categories. List includes: category_id, category_name, and parent_id.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No categories found

• 500 Internal Server Error – Exception.

DELETE /API/1.1/dashboards/(int: dashboard_id)/widget/(int : widget_id)

Delete widget for specifed dashboard.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• dashboard_id (int) – Dashboard unique id.

• widget_id (int) – Widget unique id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards found for specified username.

• 500 Internal Server Error – Exception.

PUT /API/1.1/dashboards/(int : dashboard_id)/widget

Base API function for adding a new widget to the given dashboard id.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• dashboard_id (int) – Unique dashboard id.

Optional:

None.

Data Parameters

Form Parameters

• dashboards_templates_widgets_id – Dashboard widget template id.

• widget_name – Widget name.

• widget_details – Widget details.

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• dashboards_template_id – Dashboard template id.

• boolean isSelected – true or false.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, Unable to add widget to specified dashboard:

• 500 Internal Server Error – Exception.

POST /API/1.1/dashboard/(int : dashboard_id)

Update existing dashboard for specified dashboard id.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• dashboard_id (int) – Unique dashboard id.

Optional:

None.

Data Parameters

Form Parameters

• dashboard_id – Dashboard unique id.

• dashboard_name – Dashboard name.

• dashboard_details – Dashboard details.

• boolean dashboard_group – 0 or 1.

• boolean dashboard_type – 0 or 1 (1 = Filter, 0 = Associative )

• boolean dashboard_sort – 0 or 1

• dashboard_user – User id.

• boolean dashboard_private – 0 or 1

• group_name – Group name.

• boolean isSelected – true or false

• template_base_id – Template prefix number.

• boolean saveAsTemplate – true or false

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards found for specified username.

• 500 Internal Server Error – Exception.

POST /API/1.1/dashboards/(int : dashboard_id)/widget/(int : widget_id)

Update specified widget for specified dashboard.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• dashboard_id (int) – Dashboard unique id.

• widget_id (int) – Widget unique id.

Optional:

None.

Data Parameters

Form Parameters

• widget_id – Widget unique id.

• widget_name – Widget name.

• widget_details – Widget details.

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• output_type[width] – Widget width 1 to 12

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• dashboard_id – Dashboard unique id.

• widget_sort – Widget sort.

• dashboard_height – Dashboard height. (Default: 400)

• dashboard_width – Dashboard width. (Default: 400)

• height – empty

• width – empty

• drillType – Column to drill down on. (Default: ip_src)

• template_base_id – Template prefix number.

• boolean saveAsTemplate – true or false

• widget_category_id – Widget Category id.

• category – Category

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards found for specified username.

• 500 Internal Server Error – Exception.

GET /API/1.1/dashboards/(int : dashboard_id)/widgets

Get list of widgets for specified dashbaord id. List includes widget_id, widget_name, widget_details, output_type[type, label, value, rotate, data_type, width], column_params[], where_params[], orderby_params[], limit_params, dashboard_id, widget_sort, dashboard_height, dashboard_width, height, and width.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• dashboard_id (int) – Unique dashboard id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards found for specified username.

• 500 Internal Server Error – Exception.

POST /API/1.1/search/dashboard

Search for dashboards

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order colums separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No Dashboards found.

• 500 Internal Server Error – Exception.

PUT /API/1.1/dashboard

Create new dashboard

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• dashboard_name – Dashboard name.

• boolean dashboard_group – 0 or 1.

• group_name – Group name.

• boolean dashboard_type – 0 or 1 (1 = Filter, 0 = Associative )

• dashboard_details – Details about dashboard.

• boolean dashboard_private – 0 or 1

• template_base_id – Template prefix number.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Failure to add dashboard.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/dashboard/(int : id)

Delete dashboard by dashboard id.

Access Control Requirements

Moderator.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

5.12. Reports

GET /API/1.1/reports/templates/(int : template_id)/widgets

Get list of widgets for specified report template. List includes reports_widget_template_id, widget_name, output_type[type, label, value, rotate, data_type], column_params[], where_params[], groupby_params[], orderby_params[], limit_params, and report_template_id.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – unique template id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No templates found.

• 500 Internal Server Error – Exception.

PUT /API/1.1/reports/templates/(int : template_id)/widget

Create widget for specified report template.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – Unique template id.

Optional:

None.

Data Parameters

Form Parameters

• reports_widgets_id – Widgets unique id.

• report_widget_name – Widgets name.

• report_details – Details for widget.

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• reports_id – Reports unique id.

• boolean report_sort – 0 or 1

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, Unable to add widget to specified report template.

• 500 Internal Server Error – Exception.

POST /API/1.1/reports/templates/widget/(int : widget_id)

Update specified reports template widget.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• widget_id (int) – Widget unique id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No reports widgets found for specified widget id.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/reports/templates/widget/(int : widget_id)

Delete the specified reports template widget.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• widget_id (int) – Unique widget id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

PUT /API/1.1/reports/templates

Create new report template.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• reports_id – Unique report id.

• user_id – Username id.

• group_id – Group id.

• report_template_id – Unique report id.

• report_name – Name given to report.

• details – Details for report.

• image_file – Directory to save reports default is: tmp

• cover_details – Cover page details

• date_added – Date report template was added (i.e. 2014-06-23 12:45:29 )

• report_schedule – Report schedule to run. (i.e. 2014-06-01 15:00:00 )

• report_timeperiod – C = once, D = Daily, W = Weekly, M = Monthly

• boolean report_lock – 0 or 1

• reports_options[output_type] – cvs or pdf

• username – Username

• fullname – Full name of user.

• group_name – Group name.

• reports_widgets_count – How many widgets does report contain.

• next_run – Next time report is schedule to run. (i.e. 2014-06-08 20:00:00 )

• reports_type – Empty

• endDate – End date (i.e. Wed Jun 04 2014 00:00:00 GMT-0500 (CDT) )

• begin_time – Begin time (i.e. Thu Jun 19 2014 11:51:36 GMT-0500 (CDT) )

• end_time – End time (i.e. Thu Jun 19 2014 12:51:36 GMT-0500 (CDT) )

• reports_frequency – C = once, D = Daily, W = Weekly, M = Monthly

• template_base_id – Template pre-fix. Can be empty.

• boolean saveAsTemplate – true or false

• category – Category name. Security, Executive, Compliance, Malware, Performance.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

GET /API/1.1/reports/templates

Returns json list of report templates. List includes report_template_id, report_template_name, report_template_details, report_category_id, where_params, category_name, and report_where_params.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/reports/templates/(int : template_id)

Delete specified report template.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – Unique template id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

POST /API/1.1/reports/templates/(type : template_id)

Update specified report template.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• template_id (int) – Template unique id.

Optional:

None.

Data Parameters

Form Parameters

• reports_id – Unique report id.

• user_id – Username id.

• group_id – Group id.

• report_template_id – Unique report id.

• report_name – Name given to report.

• details – Details for report.

• image_file – Directory to save reports default is: tmp

• cover_details – Cover page details

• date_added – Date report template was added (i.e. 2014-06-23 12:45:29 )

• report_schedule – Report schedule to run. (i.e. 2014-06-01 15:00:00 )

• report_timeperiod – C = once, D = Daily, W = Weekly, M = Monthly

• boolean report_lock – 0 or 1

• reports_options[output_type] – cvs or pdf

• username – Username

• fullname – Full name of user.

• group_name – Group name.

• reports_widgets_count – How many widgets does report contain.

• next_run – Next time report is schedule to run. (i.e. 2014-06-08 20:00:00 )

• reports_type – Empty

• endDate – End date (i.e. Wed Jun 04 2014 00:00:00 GMT-0500 (CDT) )

• begin_time – Begin time (i.e. Thu Jun 19 2014 11:51:36 GMT-0500 (CDT) )

• end_time – End time (i.e. Thu Jun 19 2014 12:51:36 GMT-0500 (CDT) )

• reports_frequency – C = once, D = Daily, W = Weekly, M = Monthly

• template_base_id – Template pre-fix. Can be empty.

• boolean saveAsTemplate – true or false

• category – Category name. Security, Executive, Compliance, Malware, Performance.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Exception.

GET /API/1.1/reports/categories

Get json list of dashboard categories. List includes category_id, category_name, and parent_id.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure, No categories found.

• 500 Internal Server Error – Exception.

GET /API/1.1/reports-cache/(string : username)/(string : group)

Get list of available reports for the specified username and specified group.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• username (string) – Username

• group (string) – Group

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Failure, Invalid permissions for the user specified.

• 500 Internal Server Error – Exception.

GET /API/1.1/reports-cache/(string : username)

Returns list of all reports cached for specified username.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• username (string) – Username

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Failure, Invalid permissions for the user specified.

• 500 Internal Server Error – Exception.

PUT /API/1.1/reports-cache/

Add reports to report cache.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

Form Parameters

• reports_id – Reports id.

• report_name – Report name.

• report_details – Report details.

• begin_time – Begin time (i.e. Thu Jun 19 2014 11:51:36 GMT-0500 (CDT)

• end_time – End time (i.e. Thu Jun 19 2014 12:51:36 GMT-0500 (CDT)

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

GET /API/1.1/reports/(string : username)

Returns list of all reports for specified username.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• username (string) – Username

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Failure, Invalid permissions for the user specified.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/reports/(int : report_id)/widget/(int : widget_id)

Deletes widget on specified report.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• report_id (int) – Unique report id.

• widget_id (int) – Unique widget_id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Exception.

PUT /API/1.1/reports/(int : report_id)/widget

Base API function for adding a new widget to the specified report id.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• report_id (int) – Unique report id.

Optional:

None.

Data Parameters

Form Parameters

• reports_widget_template_id – The widget template’s id.

• widget_name – Widget’s name.

• widget_details – Details for widget.

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• report_template_id – Report template id.

• report_widget_name – Name for widget in specified report.

• report_details – Details for widget in specified report.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Exception.

GET /API/1.1/report/(int : report_id)/download/(int : reports_cache_id)

Download the specified report.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• report_id (int) – Unique report id.

• reports_cache_id (int) – Unique report cache id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Exception.

POST /API/1.1/report/(type : report_id)

Update specified report.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

Form Parameters

• reports_id – Unique report id.

• user_id – Username id.

• group_id – Group id.

• report_template_id – Unique report id.

• report_name – Name given to report.

• details – Details for report.

• image_file – Directory to save reports default is: tmp

• cover_details – Cover page details

• date_added – Date report template was added (i.e. 2014-06-23 12:45:29 )

• report_schedule – Report schedule to run. (i.e. 2014-06-01 15:00:00 )

• report_timeperiod – C = once, D = Daily, W = Weekly, M = Monthly

• boolean report_lock – 0 or 1

• reports_options[output_type] – cvs or pdf

• username – Username

• fullname – Full name of user.

• group_name – Group name.

• reports_widgets_count – How many widgets does report contain.

• next_run – Next time report is schedule to run. (i.e. 2014-06-08 20:00:00 )

• reports_type – Empty

• endDate – End date (i.e. Wed Jun 04 2014 00:00:00 GMT-0500 (CDT) )

• begin_time – Begin time (i.e. Thu Jun 19 2014 11:51:36 GMT-0500 (CDT) )

• end_time – End time (i.e. Thu Jun 19 2014 12:51:36 GMT-0500 (CDT) )

• reports_frequency – C = once, D = Daily, W = Weekly, M = Monthly

• template_base_id – Template pre-fix. Can be empty.

• boolean saveAsTemplate – true or false

• category – Category name. Security, Executive, Compliance, Malware, Performance.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Exception.

POST /API/1.1/reports/(int : report_id)/widget/(int : widget_id)

Update specified widget for specified report.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• report_id (int) – Report unique id.

• widget_id (int) – Widget unique id.

Optional:

None.

Data Parameters

Form Parameters

• reports_widgets_id – Reports widget unique id.

• report_widget_name – Report widget’s name.

• report_details – Report widget’s details.

• output_type[type] – Graph type.

• output_type[label] – Widget Label (Y-Axis)

• output_type[value] – Widget Value (X-Axis)

• output_type[rotate] – yes or no

• output_type[data_type] – Events, Resource, Incidents, Vulnerabilities, Audit

• output_type[width] – Widget width 1 to 12.

• column_params[] – Array of column names. One for each column name.

• where_params[] – Array of where statements. One for each where statement.

• groupby_params[] – Array of group by statements. One for each group by statement.

• orderby_params[] – Array of order by statements. One for each order by statement.

• limit_params – Limit the amount of records for widget.

• reports_id – Report unique id.

• boolean report_sort – 0 or 1

• boolean isSelected – true or false

• widget_name – Widget name.

• widget_details – Widget details.

• template_base_id – Template prefix number.

• boolean saveAsTemplate – true or false.

• widget_category_id – Widget category id.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Exception.

GET /API/1.1/reports/(int : report_id)/widgets

Returns a json list of all widgets associated with specified report.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• report_id (int) – Unique report id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – Exception.

GET /API/1.1/reports-cache-status/(int : report_id)/(int : status)

Update specified running report status.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• report_id (int) – Unique report id.

• status (int) – Status 0 = Pending, 1 = In Progress, 2 = Completed, 3 = Failed, 4 = Cancelling, 5 = Cancelled.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 403 Forbidden – Exception.

POST /API/1.1/search/report

Get list of all reports.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

Form Parameters

• column[] – Array of column names. One for each column name.

• group_by – How to group columns separated by a comma.

• order_by – How to order columns separated by a comma. DESC = Descending and ASC = Ascending

• where[] – Where statement. One for each whare statement.

• limit – Limit the amount of records.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

PUT /API/1.1/report

Create new report.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

Form Parameters

• report_name – Name given to report

• group_name – Group name.

• reports_type – Empty

• reports_details – Details showing who this report is for.

• cover_details – Cover page details.

• reports_options[output_type] – csv or pdf

• report_schedule – Start date (i.e. 2014-06-01 05:00:00 )

• endDate – End date (i.e. Wed Jun 04 2014 00:00:00 GMT-0500 (CDT) )

• begin_time – Begin time (i.e. Thu Jun 19 2014 11:51:36 GMT-0500 (CDT) )

• end_time – End time (i.e. Thu Jun 19 2014 12:51:36 GMT-0500 (CDT) )

• template_base_id – Template id.

• report_details – Report details

• reports_frequency – C = once, D = Daily, W = Weekly, M = Monthly

• next_run – When this report is schedule to run next. (i.e. 2014-06-04 10:00:00 )

Fom report_timeperiod

C = once, D = Daily, W = Weekly, M = Monthly if once you have to include a date: C:2014-06-04 05:00:00

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 403 Forbidden – failure, Unable to add report.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/reports-cache/(int : id)

Delete specific report cache.

Access Control Requirements

Moderator.

URL Parameters

Required:

Parameters

• id (int) – Unique report cache id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/report/(int : id)

Delete specific report.

Access Control Requirements

Moderator.

URL Parameters

Required:

Parameters

• id (int) – Unique report id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

5.13. Widgets Templates

GET /API/1.1/widgets/categories

Returns a json list of all widget categories.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

GET /API/1.1/widgets/templates

Returns a json list of all widget templates.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/widgets/templates/(int : widget_template_id)

Delete specified widget template.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• widget_template_id (int) – Unique widget template id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

PUT /API/1.1/widgets/templates

Adds specified widget template.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• output_type[width] – Width of widget 1 to 12

• output_type[label] – Y-Axis column name.

• output_type[value] – X-Axis column name.

• output_type[type] – Graph Type.

• output_type[data_type] – Events, Resource, incidents, Vulnerabilities, Audit

• output_type[col_sort][] – array of column names. one for each item in the array.

• widget_name – Name of widget

• widget_details – Details of what widget will do.

• column_params[] – Column names. One for each column you want.

• where_params[] – Empty

• groupby_params[] – Group by these specified column’s

• orderby_params[] – Order by these specified column either ASC (Ascending) or DESC (Descending)

• limit_params – Limit the records to this name.

• template_base_id – If you would like to add a prefix to the template id.

• saveAsTemplate – Is this to be saved as a template true or false

• widget_category_id – Category id.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Failure, No dashboards found for specified username.

• 500 Internal Server Error – Exception.

POST /API/1.1/widgets/templates/(type : widget_template_id)

Update specifed widget template.

Access Control Requirements

None.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

Form Parameters

• widget_template_id – Widget template unique id.

• widget_name – Name of widget

• widget_details – Details of what widget will do.

• output_type[width] – Width of widget 1 to 12

• output_type[label] – Y-Axis column name.

• output_type[value] – X-Axis column name.

• output_type[type] – Graph Type.

• output_type[data_type] – Events, Resource, incidents, Vulnerabilities, Audit

• column_params[] – Column names. One for each column you want.

• where_params[] – Empty

• groupby_params[] – Group by these specified column’s

• orderby_params[] – Order by these specified column either ASC (Ascending) or DESC (Descending)

• limit_params – Limit the records to this name.

• widget_category_id – Widget category id.

• category_name – Category name: Security, Executive, Compliance, Malware, Performance.

• boolean isSelected – true or false.

• template_base_id – If you would like to add a prefix to the template id.

• boolean saveAsTemplate – Is this to be saved as a template true or false

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

5.14. Shard Management and Stats Gathering

GET /API/1.1/shards/stats

List each shard stats.

Access Control Requirements

Admin.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

GET /API/1.1/shards/list

List each shard including host information and which group tags are associated.

Access Control Requirements

Admin.

URL Parameters

Required:

None

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

GET /API/1.1/shards/list/available/(string : group)

List each shard specified group exist on.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• group (string) – Name of group.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

GET /API/1.1/shards/move

Move specified group to specified shard.

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• name (string) – Name of group.

• shard (string) – Name of shard.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Invalid request, no group specified.

• 400 Bad Request – Failure, Invalid request, no shard specified.

GET /API/1.1/shards/group

List shard that specifed group collection exist on.

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• group (string) – Name of group.

• collection (string) – Name of collection.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Invalid request, no group specified.

• 400 Bad Request – Failure, Invalid request, no collection specified.

GET /API/1.1/shards/group-storage

Get chunk storage size by specified group and collection.

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• group (string) – Name of group.

• collection (string) – Name of collection.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Invalid request, no group specified.

• 400 Bad Request – Failure, Invalid request, no collection specified.

GET /API/1.1/shards/add

Add new shard.

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• name (string) – Name of shard.

• hostname (string) – Hostname of shard.

• maxSize (int) – Shard size in GigaBytes.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Invalid request, no shard name specified.

• 400 Bad Request – Failure, Invalid request, no hostname specified.

POST /API/1.1/shards/size/(string : shard)/(int : size)

Update shard size.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• shard (string) – Name of hostname.

• maxSize (int) – Shard size in MegaBytes

Optional:

None.

Data Parameters

Form Parameters

• withCredentials – true

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Unable to update shard size.

PUT /API/1.1/shards/tags/(string : shard)

Add tag to specified shard

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• shard (string) – Shard name.

Query Parameters

• tag – Tag name.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Unable to add shard tag.

DELETE /API/1.1/shards/tags/(string : shard)

Delete tag from specified shard

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• shard (string) –

Query Parameters

• tag (string) – tag name.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Failure, Unable to remove shard tag.

5.15. Archive Management

GET /API/1.1/archive/profile

Get archive profile by group.

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• group (string) – Group name.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

PUT /API/1.1/archive/profile

Create a archive profile by group.

Access Control Requirements

Admin.

URL Parameters

Required:

Query Parameters

• group (string) – Group name.

Optional:

None.

Data Parameters

Form Parameters

• group – Group name.

• expirationDays – Amount of days to keep data live.

• action – What to do after expiration days delete or archive

• encryption – false. encryption will be implemented soon.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 404 Not Found – Failure, Invalid group value provided.

• 500 Internal Server Error – Exception.

5.16. Archive Availability & Import Management

POST /API/1.1/archive/records

Returns a json list of all archive records and their locations.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• undefined – Empty post request.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Exception, Unable to process request.

POST /API/1.1/archive/records/(string : group)

Returns a json list of all archive records and their locations for specified group.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• group (string) – Group name.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Exception, Unable to process request.

5.17. Notifications

GET /API/1.1/notifications

Get list of notification rules for specified group and/or sub-groups.

Access Control Requirements

None.

URL Parameters

Required:

Query Parameters

• recursive (boolean) – true or false

• group (string) – Group name.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

PUT /API/1.1/notifications

Add a notifications for specified group

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• data_type – Events, Resource, Incidents, Vulnerabilities, Audit

• rules[] – One or more rules.

• filter_name – Name for notification.

• filter_details – Details for what notification does.

• group_name – Group name that notification applies too.

• action_time – Amount of minutes to included in one notification incident.

• action_mail – What is included in the e-mail notification. Accepts url encoded tokens like %25payload%25

• actions[0][key] – incident

• actions[0][value] – 1 = 5 Minutes, 2 = 15 Minutes, 3 = 30 Minutes, 4 = 60 Minutes, 5 = 90 Minutes, 6 = 3 Hours, 7 = 6 Hours, 8 = 12 Hours

• actions[1][key] – notification

• actions[1][value] – What is included in the e-mail notification. Accepts url encoded tokens like %25payload%25

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

DELETE /API/1.1/notifications/(int : id)

Delete notification by id.

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• id (int) – Unique notification id.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

POST /API/1.1/notifications/(int : id)

Add a notifications for specified group

Access Control Requirements

Admin.

URL Parameters

Required:

Parameters

• id (int) – Unique notification id.

Optional:

None.

Data Parameters

Form Parameters

• data_type – Events, Resource, Incidents, Vulnerabilities, Audit

• rules[] – One or more rules.

• filter_name – Name for notification.

• filter_details – Details for what notification does.

• group_name – Group name that notification applies too.

• action_time – Amount of minutes to included in one notification incident.

• action_mail – What is included in the e-mail notification. Accepts url encoded tokens like %25payload%25

• actions[0][key] – incident

• actions[0][value] – 3 = 30mins

• actions[1][key] – notification

• actions[1][value] – What is included in the e-mail notification. Accepts url encoded tokens like %25payload%25

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 500 Internal Server Error – Exception.

5.18. Saved Search

DELETE /API/1.1/saved-search/(string : name)

Delete saved search by name.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• name (string) – Name of saved search

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 500 Internal Server Error – Exception.

GET /API/1.1/saved-search

Returns a list of saved searches.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

Query Parameters

• name (string) – Group name. (Default: top group available for user.)

• recursive (boolean) – true or false. (Default: true.)

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Exception, Invalid results.

PUT /API/1.1/saved-search

Create new saved search.

Access Control Requirements

None.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• dataType – Events, Resources, Incidents, Vulnerabilities

• status – public or private

• name – Name to save search as.

• details – Detail description of what saved search will do.

• query – actual query to perform.

• format – json

• group_name – Limit search to group name.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Failure, Invalid field name.

• 400 Bad Request – Failure, Invalid field details.

• 400 Bad Request – Failure, Invalid field status.

• 400 Bad Request – Failure, Invalid field query.

• 400 Bad Request – Failure, Invalid field dataType.

• 400 Bad Request – Failure, Invalid field group_name.

• 500 Internal Server Error – Exception.

POST /API/1.1/saved-search/(int : id)

Update existing saved search.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• id (int) – Unique saved search id.

Optional:

None.

Data Parameters

Form Parameters

• dataType – Events, Resources, Incidents, Vulnerabilities

• status – public or private

• name – Name to save search as.

• details – Detail description of what saved search will do.

• query – actual query to perform.

• format – json

• group_name – Limit search to group name.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 400 Bad Request – Failure, Invalid field name.

• 400 Bad Request – Failure, Invalid field details.

• 400 Bad Request – Failure, Invalid field status.

• 400 Bad Request – Failure, Invalid field query.

• 400 Bad Request – Failure, Invalid field dataType.

• 400 Bad Request – Failure, Invalid field group_name.

• 500 Internal Server Error – Exception.

5.19. Tools

All tool request are performed on the data tier.

GET /API/1.1/tools/whois/(string : host)

Perform a whois lookup on specified host.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• host (string) – Host name to lookup.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

GET /API/1.1/tools/traceroute/(string : host)

Perform a traceroute on specified host.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• host (string) – Host name to lookup.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

GET /API/1.1/tools/ping/(string : host)

Perform a ping on specified host.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• host (string) – Host name to lookup.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

GET /API/1.1/tools/dns-lookup/(string : host)

Perform a DNS lookup on specified host.

Access Control Requirements

None.

URL Parameters

Required:

Parameters

• host (string) – Host name to lookup.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

5.20. System Information

GET /API/1.1/system

Returns a system_description and authentication login message.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

None.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Exception.

PUT /API/1.1/system

Update system description and authentication login message.

Access Control Requirements

Admin.

URL Parameters

Required:

None.

Optional:

None.

Data Parameters

Form Parameters

• hawk – true

• system_description – System description.

• authentication_login_message – Authentication login message.

• system_company_name – Company name.

• system_company_address – Company address.

Success Response:

Status Codes

• 200 OK – Success.

Error Response:

Status Codes

• 404 Not Found – Failure.

• 404 Not Found – Access Control Permissions failure for the specified user, exiting.

• 400 Bad Request – Exception.