Getting Started with NetworkSage

This guide will show you how to create an account, submit a sample, and view its summary.

Account Setup

To get started with NetworkSage, you'll need to register for an account. To do so, visit https://networksage.seclarity.io/register and create your account.Account Registration Page

At this point, you'll be asked to choose which plan you'd like to sign up for. To learn more about what each plan offers, please check out our Pricing page. For this guide, we'll select the Free tier.

Once you've successfully confirmed your account (via the email provided), you're ready to login and get your API key! If instead you'd like to upload a sample directly via the UI, you can do so by visiting the NetworkSage home page as an authenticated user.

Accessing the API

Once you login to your account, you'll need to enable API access. This is accomplished by navigating to the user menu and selecting API Keys:API Keys Menu Option

Press the Enable API Access button to get your API key. Once you have it, please store it in a safe place to avoid abuse.Requesting API Key

You're now ready to interact with NetworkSage via API! Let's walk through uploading your first sample.

Uploading a Sample

The first thing we'll need to do is open a terminal or command line window to interact with the API. Additionally, open a new browser tab and visit our API Docs to see the latest information on our APIs. Here we'll reproduce the Python3 sample upload code and walk through uploading a Zeek sample.Upload Sample API Docs

In your terminal, start a Python3 interactive session and replace my information below with yours:


  davids-air: ~ 0xd$ python3
  >>> import requests
  >>> url = "https://api.seclarity.io/upload/v1.0/uploader"
  >>> payload = {'type': 'zeek'}
  >>> files = [('file', ('zeek_demo.conn.log', open('testing/conn.log', 'rb'), 'application/octet-stream')), 
               ('zeekDnsFile', ('dns.log', open('testing/dns.log', 'rb'), 'application/octet-stream'))
              ]
  >>> import os
  >>> headers = {'apikey': os.environ.get("NETWORKSAGE_API_KEY")}
  >>> response = requests.request("POST", url, headers=headers, data=payload, files=files)
  >>> print(response.text)
  {"error":false,"body":{"sampleId":"1c2aed8dedd64ee7996f0e0948400221"}}

A few things to note here. First, you'll need to make sure that you have the Python requests library installed (you can find instructions here. Second, you'll need to provide your API key to the POST. In my example above I stored my API key as an environment value on my OS X system by typing


export NETWORKSAGE_API_KEY="api_key_goes_here"

Finally, we're using Zeek data for this example, but the flow looks nearly identical for uploading other formats. To learn more about other formats we support and available open source tooling, please check out our FAQs. Now that we have a sample ID for our sample, we can use that to request its summary.

Requesting Sample Summary

Using the sample ID returned in the section above, we'll need to ask NetworkSage to generate the sample summary and then retrieve it. Using details captured in our API docs, replace my information below with yours:


  >>> url = "https://api.seclarity.io/sec/v1.0/samples/1c2aed8dedd64ee7996f0e0948400221/summary"
  >>> payload = {}
  >>> headers = {'apikey': os.environ.get("NETWORKSAGE_API_KEY")}
  >>> response = requests.request("POST", url, headers=headers, data=payload)
  >>> print(response.text)
  {"error":false,"body":"Request submitted. Use \u0027GET /samples/1c2aed8dedd64ee7996f0e0948400221/summary\u0027 endp
  oint to get the result once it is ready"}

As the server response suggests, we'll now need to request the summary. This is as simple as changing the POST in the request to a GET:


  >>> response = requests.request("GET", url, headers=headers, data=payload)
  >>> print(response.text)
  {"error":false,"body":{"status":"generated","summary":"{\"confidence\":\"High\",\"details\":\"_NetworkSage_ 
  has observed activity to:\\n• 1 known \`Malicious\` site\\n• 2 suspected \`Attack Vector\` sites\\n\\nDetails about 
  each are as follows:\\n\\nThere are no known Attack Vectors in this sample, but there are 2 which we suspect could 
  be Attack Vectors. \\t1. \`199.36.158.100:443\` (first seen here at 142.756562s.)
  \\n\\t*Confidence:* Medium\\n\\t*Description:* \`\`\`We have Medium confidence that this site is acting as an Attack

Once the summary is generated (which generally takes less than a minute), you should have the full summary that NetworkSage produces for a sample. The response will contain a string that can be re-loaded into its underlying JSON-encoded Markdown content.


  >>> import json
  >>> summary = json.loads(response.text)["body"]["summary"]
  >>> print(summary)
  {"confidence":"High","details":"_NetworkSage_ has observed activity to:\n• 1 known \`Malicious\` site\n• 2 suspected
  \`Attack Vector\` sites\n\nDetails about each are as follows:\n\nThere are no known Attack Vectors in this sample, 
  but there are 2 which we suspect could be Attack Vectors. \t1. \`199.36.158.100:443\` (first seen here at 
  142.756562s.)\n\t*Confidence:* Medium\n\t*Description:* \`\`\`We have Medium confidence that this site is acting as 
  an Attack Vector in this sample. Activity to this site occurs in a brief period of this sample where we believe a 

Additional Resources

That's the end of our Getting Started guide, but there's so much more that you can do with NetworkSage! To dig deeper, we recommend the following resources: