Compatibility Notice
Make sure to check your product version, and then review and update your add-ons and scripts leveraging Netwrix Auditor Integration API. Download the latest add-on version in the Add-on Store.
| Property in 8.0 – 8.5 | New property in 9.0 and above |
|---|---|
- XML: <AuditedSystem></AuditedSystem> - JSON: "AuditedSystem" | - XML: <DataSource></DataSource> - JSON: "DataSource" |
- XML: <ManagedObject></ManagedObject> - JSON: "ManagedObject" | - XML: <MonitoringPlan> `````` `<Name>`Name</Name> `````` <ID>Unique ID</ID> `````` </MonitoringPlan> - JSON: "MonitoringPlan" : { `````` "ID": "{Unique ID}", `````` "Name": "Name" `````` } Now the MonitoringPlan contains two sub-entries: ID and Name. The ID property is optional and is assigned automatically by the product. |
| — | - XML: <Item> `````` `<Name>`Item name</Name> `````` </Item> - JSON: "Item": {"Name": "Item name"} |
To learn more about input and output Activity Record structure, refer to Activity Records.
Error Details
On error, most requests contain an error description in the response body (except some requests with empty body, e.g., 404, 405). Response Status Codes
The error details include:
| Block | Description |
|---|---|
| Category | Defines the type of error (XML formatting-related error, invalid input-related error, etc.) |
| Description | Provides details about this error. |
| Location | (optional) Provides a link to a corrupted text in request. XML is considered a default format for Netwrix Auditor Integration API. Error location is defined in XML format. |
The error details have the format similar to the following:
| Format | Example |
|---|---|
| XML | <?xml version="1.0" encoding="UTF-8" ?> `````` <ErrorList xmlns="http://schemas.netwrix.com/api/v1/"> `````` <Error> `````` <Category>Category</Category> `````` <Description>Error Description</Description> `````` <Location>Error Location</Location> `````` </Error> `````` </ErrorList> |
| JSON | { `````` "ErrorList": [ `````` { `````` "Category": "Category", `````` "Description": "Error Description", `````` "Location": "Error Location" `````` } `````` ] `````` } |
Review examples below to see how error details correspond to invalid requests.
| Request | Error details returned |
|---|---|
Invalid request: XML: curl -H "Content-Type: application/xml; Charset=UTF-8" https://WKSWin12R2:9699/ netwrix/api/v1/activity_records/search -u Enterprise\ NetwrixUser:NetwrixIsCool --data-binary @C:\APIdocs\Search.xml <?xml version="1.0" encoding="utf-8"?> `````` <ActivityRecordSearch xmlns="http://schemas. netwrix.com/api/v1/activity_records/"> `````` <FilterList> `````` <Who>Administrator</Who> `````` <DataSource>Active Directory `````` <Action>Modified</Action> `````` </FilterList> `````` </ActivityRecordSearch> - JSON: curl -H "Content-Type: application/json; Charset=UTF-8" https://WKSWin12R2:9699/ netwrix/api/v1/activity_records/search?format=json -u Enterprise\NetwrixUser: NetwrixIsCool --data-binary @C:\APIdocs\Search.json { `````` "FilterList": { `````` "Who": "Administrator", `````` "DataSource": "Active Directory `````` "Action": "Added" `````` } `````` } | 400 Bad Request - XML: <?xml version="1.0" encoding="UTF-8" ?> `````` <ErrorList xmlns="http://schemas.netwrix.com/api/v1/"> `````` <Error> `````` <Category>XMLError</Category> `````` <Description>0xC00CE56D End tag 'FilterList' does not match the start tag 'DataSource' `````` </Description> `````` </Error> `````` </ErrorList> - JSON: If JSON is corrupted, server returns 500 Internal Server Error with empty body. |
Invalid request: - XML: curl https://WKSWin12R2:9699/ netwrix/api/v1/activity_records/ enum?count=FIVE -u Enterprise\ NetwrixUser:NetwrixIsCool - JSON: curl https://WKSWin12R2:9699/ netwrix/api/v1/activity_records/ enum?format=json&count=FIVE -u Enterprise\NetwrixUser: NetwrixIsCool | 400 Bad Request - XML: <?xml version="1.0" encoding="UTF-8" ?> `````` <ErrorList xmlns="http://schemas.netwrix.com/api/v1/"> `````` <Error> `````` <Category>InputError</Category> `````` <Description>Invalid count parameter specified. Error details: 0x80040204 Cannot convert the attribute data type `````` </Description> `````` </Error> `````` </ErrorList> - JSON: { `````` "ErrorList": [ `````` { `````` "Category": "InputError", `````` "Description": "Invalid count parameter specified. Error details: 0x80040204 Cannot convert the attribute data type" `````` } `````` ] `````` } |
Valid request, but the Audit Database is unreachable: - XML: curl https://WKSWin12R2:9699/ netwrix/api/v1/activity_records/enum -u Enterprise\ NetwrixUser:NetwrixIsCool - JSON: curl https://WKSWin12R2:9699/ netwrix/api/v1/activity_records/enum?format=json -u Enterprise\NetwrixUser: NetwrixIsCool | 500 Internal Server Error - XML: <?xml version="1.0" encoding="UTF-8" ?> `````` <ErrorList xmlns="http://schemas.netwrix.com/api/v1/"> `````` <Error> `````` <Category>ServerError</Category> `````` <Description>0x80040C0A SQL Server cannot be contacted, connection is lost (0x80040C0A SQL Server cannot be contacted, connection is lost (0x80004005 [DBNETLIB][ConnectionOpen (Connect()). ]SQL Server does not exist or access denied.)) [0x00007FFDCC06BBC8,0x00007FFDB99EF4BA; 0x00007FFDB99BEEEF,0x00007FFDB99EF4DC] `````` </Description> `````` </Error> `````` </ErrorList> - JSON: { `````` "ErrorList": [ `````` { `````` "Category": "ServerError", `````` "Description": "0x80040C0A SQL Server cannot be contacted, connection is lost (0x80040C0A SQL Server cannot be contacted, connection is lost (0x80004005 [DBNETLIB][ConnectionOpen (Connect()). ]SQL Server does not exist or access denied.)) [0x00007FFDCC06BBC8,0x00007FFDB99EF4BA; 0x00007FFDB99BEEEF,0x00007FFDB99EF4DC]" `````` } `````` ] `````` } |
Integration API Ports
Review a full list of protocols and ports required for add-ons or any queries leveraging Netwrix Auditor Integration API.
- Allow outbound connections from the dynamic (1024 - 65535) local port on the computer where Netwrix Auditor Server resides.
- Allow outbound connections to remote ports on the source and inbound connections to local ports on the target.
On any computer you plan to host the add-on (source), allow outbound connections to remote 9699 TCP port. On the computer where Netwrix Auditor Server resides (target), allow inbound connections to local 9699 TCP port.
| Add-on | Port | Protocol | Source | Target | Purpose |
|---|---|---|---|---|---|
| All add-ons or queries | 9699 | TCP | Script or query host | Netwrix Auditor Server | The default Netwrix Auditor Integration API port. However, you can configure another TCP port for that purpose. |
| AlienVault USM | 53 | UDP/TCP | Script host | DNS Server | DNS Client |
| Amazon Web Services | 443 | TCP | Script host | Amazon Web Services | — |
| 53 | UDP/TCP | Script host | DNS server | DNS Client | |
| - Event Log Export - IBM QRadar - Intel Security - LogRhythm - SolarWinds Log & Event Manager - Splunk | 53 | UDP/TCP | Script host | DNS server | DNS Client |
| CEF Export | 53 | UDP/TCP | Script host | DNS server | DNS Client |
| - Cisco Network Devices - Privileged User Monitoring - General Linux Syslog | 514 | UDP | Cisco network devices | Service host | The default port for Cisco network devices remote Syslog logging. However, you can configure another UDP port for that purpose. |
| 53 | UDP | Service host | DNS server | DNS Client | |
| HPE ArcSight | 515 | TCP | Script host | ArcSight Logger | — |
| 514 | UDP | Script host | ArcSight Logger | — | |
| 53 | UDP/TCP | Script host | DNS server | DNS Client | |
| 53 | UDP | Script host | DNS server | DNS Client | |
| RADIUS Server | 139 | TCP | Script host | RADIUS server | RPC/NP Eventlog |
| 445 | TCP | Script host | RADIUS server | RPC/NP Eventlog | |
| 137 | UDP | Script host | RADIUS server | RPC/NP Eventlog | |
| 138 | UDP | Script host | RADIUS server | RPC/NP Eventlog | |
| 135 | TCP | Script host | RADIUS server | RPC Endpoint Mapper Eventlog | |
| 1024 – 65535 (Dynamically assigned) | TCP | Script host | RADIUS server | RPC Eventlog | |
| 53 | UDP/TCP | Script host | DNS server | DNS Client |
Response Status Codes
| Code | Status | Write Activity Records | Retrieve, search Activity Records |
|---|---|---|---|
| 200 OK | Success | Success. The body is empty. Activity Records were written to the Audit Database and the Long-Term Archive. | Success. The body contains Activity Records. Activity Records were retrieved from the Audit Database. |
| 400 Bad Request | Error | Error validating Activity Records. Make sure the Activity Records are compatible with the Schema. | Error validating request parameters or post data. Make sure the post data files (Continuation mark, Search parameters) are compatible with their schemas and the ?count= parameter is valid. |
| 401 Unauthorized | Error | The request is unauthorized and the body is empty. See for API Endpoints more information. | |
| 404 Not Found | Error | Error addressing the endpoint. The body is empty. The requested endpoint does not exist (e.g., /netwrix/api/v1/mynewendpoint/). | |
| 405 Method Not Allowed | Error | Error addressing the endpoint. The body is empty. Wrong HTTP request was sent (any except POST). | Error addressing the endpoint. The body is empty. Wrong HTTP request was sent (any except GET or POST). |
| 413 Request Entity Too Large | Error | Error transferring files. The body is empty. The posted file exceeds supported size. | |
| 500 Internal Server Error | Error | Error writing Activity Records to the Audit Database or the Long-Term Archive: - One or more Activity Records were not processed. - Netwrix Auditor license has expired. - Internal error occurred. | Error retrieving Activity Records from the Audit Database: - Netwrix Auditorlicense has expired. - The Netwrix Auditor Archive Service is unreachable. Try restarting the service on the computer that hosts Netwrix Auditor Server. - Internal error occurred. |
| 503 Service Unavailable | Error | The Netwrix Auditor Archive Service is busy or unreachable. Try restarting the service on the computer that hosts Netwrix Auditor Server. | — |
Most failed requests contain error in the response body (except those with empty body, e.g., 404, 405). Error Details