Postman for NetWitness

[JoshRandall]

If you've ever done any work testing against an API (or even just for fun), then you've likely come across a number of tools that aim to make this work (or fun) easier.

Postman is one of these tools, and one of its features is a method to import and export collections of API methods that enable individuals to begin using those APIs much more easily and quickly than if, say...they only have a bunch of docs to get them started.

As NetWitness is a platform with a number of APIs and a number of docs to go along with them, a Postman collection detailing the uses, requirements, options, etc. of these APIs should (I hope) be a useful tool that individual and teams can leverage to enable more efficient and effective use of the NetWitness platform....as well as with any other tool that you may want to integrate with NetWitness via its APIs.

With that in mind, I present a Postman Collection for NetWitness.  This includes all the Endpoint APIs, all the Respond APIs, and the more commonly used Events (A.K.A. SDK) APIs --> Query, Values, Content, and Packets. Simply import the attached JSON file into Postman, fill in the variables, and start API'ing.

A few notes, tips, and how-to's....

• upon importing the collection, the first thing you should do is update the variables to match your environment
  
  
• the rest_user / rest_pass variables are required for the Endpoint and Respond API calls
  • the NW account you use here can be created/managed in the NW UI in Admin/Security --> Users & Roles tabs
  • the role assigned to the account must have the integration-server.api.access permission, as well as any underlying permissions required to fulfill the request
  • e.g.: if you're querying Endpoint APIs, you'll need integration-server.api.access as well as endpoint-server permissions
    
• the svc_user / svc_pass variables are required for the Events API calls
  • the NW account you use here can be created/managed in the NW UI in Admin/Services --> <core_service> --> Security --> Users & Roles tabs
  • the role assigned to the account must have the sdk.content, sdk.meta, and sdk.packets permissions, as well as any additional permissions necessary to account for Meta and Content Restriction settings you may be using
    
• every Respond and Endpoint call will automatically create and update the accessToken and refreshToken used to authenticate its API call
  
  • so long as your rest_user and rest_pass variables are correct and the account has the appropriate permissions to call the Respond and/or Endpoint node, there is no need to manually generate these tokens
  • that said, the API calls to generate tokens are still included so you can see how they are being made
• several of the Endpoint APIs, when called, will create and update variables used in other Endpoint APIs
  • the first of these is the Get Services call, which lists all of the endpoint-server hosts and creates variables that can be used in other Endpoint API calls
    • the names of these variables will depend on the names of each service as you have them configured in the NW UI
      
  • the second of these is the Get Hosts call, which lists all of the endpoint agents/hosts reporting to the queried endpoint-server and creates a variable of each hostname that can be used in other Endpoint API calls
    
    
    • this one may be a bit unwieldy for many orgs, though, because if you have 2000 agents installed, this will create 2000 variables - 1 for each host - if you have 20,000 agents installed, or 200,000.... 
    • you may not want all those hostname variables, so you can adjust how many get created, or disable it altogether, by modifying or deleting or commenting out the javascript code in the Tests section of the Get Hosts call
      

Any questions, comments, concerns, suggestions, etc...please let me know.

sanitized_NetWitness.postman_collection.json.zip

[AmauryDroux]

Hello Josh,

Thank you for this great work. As you said API system is a must have to interconnect different tools together, so thank you for working in this direction.

I am testing the Events API calls and I am having some permissions issue for some calls, even if I use an Administrator user (with every permissions) :

- With Values calls :

   I can do this kind of call :

            https://{{broker}}/sdk?force-content-type=application/json&msg=values&size=20&fieldName=ip.src"

   But I cannot add a where clause like this :

            https://{{broker}}/sdk?force-content-type=application/json&msg=values&size=20&fieldName=ip.src&where=ip.dst = 8.8.8.8"

   this return a 401 Unauthorized error.

- With Query calls : what ever I try I am getting 401 error as well...

Could you tell me, please, what I am doing wrong here or what I missed ?

Thank you in advance for your help

Amaury D

[JoshRandall]

Hi Amaury,

The problem in that query is the spaces within your where clause  ip.dst = 8.8.8.8

You either need to remove the space  ip.dst=8.8.8.8

…or URL-encode them  ip.dst%20=%208.8.8.8

If you’re doing this all in Postman, it will automatically handle this for you when making the actual API calls, even if these types of syntax changes are not visible in the query parameters or URL bar.

[DanielSpier]

For anyone using the NetWitness API token management manually (rather than relying on the pre-request scripts), please note that there is a mistake in the Auth > GetToken_refreshToken call. Under the Body section, the token variable should be {{refreshToken}}, not {{accessToken}}. If you're receiving a 400 error for "unknown user," update the variable and re-run GetToken_user+pass then GetToken_refreshToken.