Package: networksage-wrappers
networksage-wrappersThis repository contains publicly-released wrappers intended to make working with NetworkSage's APIs exceptionally easy. Note that all functionality inside will require either a free or paid API key. To request an API key, please register for an account athttps://networksage.seclarity.io/register.What is NetworkSage?The NetworkSage platform, first and foremost, acts as a lightweight, privacy-maintaining enrichment layer for your network traffic. It takes network flows (which we callSecflows), categorizes them with one of a couple dozen labels (see ourGlossaryfor details), and compares them with the global dataset of known activity. For every Secflow, it returns:how common it is globallywhich categorization it hasany metadata the security community has providedTo visually illustrate, refer to the following (taken from a publicsamplewe found while creating our firstThreat Report).When this sample was uploaded to NetworkSage, all Secflows were automatically categorized and their global commonality was identified:In addition, many of thoseDestinations(an IP or Domain name plus its port) had additional metadata provided by the security community. That information was made available inline:Some of the categories associated with certain Secflows also indicated specificBehaviorwas happening. That information (also provided by the community) was shared for more in-depth knowledge:Finally, some of the Behaviors (when seen in a particular order within some period of time) actually identified more complex interactions that we callEvents:InstallationTo install thenetworksage-wrapperspackage, simply type the following:pip install networksage-wrappersAPI Wrappersmodule name:wrappersWith the release of our public APIs, all of the information available in the UI (and more!) is now available directly via API call.
To import this module into your project, type the following:from networksage_wrappers.wrappers import wrappersFrom there, each of the following APIs can be called via the mentioned wrapper.Available APIsRegardless whether or not you use this package, the following APIs are available to users:1. Sample UploadEndpoint URL:https://api.seclarity.io/upload/v1.0/uploaderTakes one of oursupported file formats, uploads it to NetworkSage (to your private view, if you are a paying customer), and converts it into our Secflow format. Returns the sample's UUID.Relevant Wrapper:upload_sample2. List of Uploaded SamplesEndpoint URL:https://api.seclarity.io/upload/v1.0/uploads/listLists information about all files you have uploaded.Relevant Wrapper:list_my_samples3. Get Sample Metadata for Private SampleEndpoint URL:https://api.seclarity.io/sec/v1.0/samples/<sample_uuid>Lists high-level metadata about a particular sample. It does not provide the enriched data.Relevant Wrapper:get_private_sample_metadata4. Get Secflows for Private SampleEndpoint URL:https://api.seclarity.io/sec/v1.0/samples/<sample_uuid>/listReturns all Secflows from the sample identified via UUID.Relevant Wrapper:get_secflows_from_sample5. Get Secflows for Public SampleEndpoint URL:https://api.seclarity.io/public/v1.0/secflows/<sample_public_uuid>/list/aggregatedReturns all Secflows from the sample identified via a public UUID. A public UUID will be generated for any samples uploaded that are not set to private. Note that this endpoint also provides an aggregated view ofallsample contents, not just Secflows.Relevant Wrapper:get_secflows_from_sample6. Get Global Count for SecflowEndpoint URL:https://api.seclarity.io/sec/v1.0/secflows/<flowid>/countReturns the number of global samples a given Secflow has been observed in. This can be easily used to understand how common some kind of activity to a particular Destination is globally.Relevant Wrapper:get_global_count_for_secflow7. Get Metadata about a DestinationEndpoint URL:https://api.seclarity.io/sec/v1.0/destinations/<destination_name:port>Returns any metadata we know for the particular Destination. This can include:TitleDescriptionRelevanceTagsThe list above will likely expand over time. For additional details about what each type of metadata above means, please refer to ourglossary.Use Cases:Has anyone seen a site I've seen?Does the community know that a site isnot interesting?known malicious?What category is this Destination associated with?Are any of this domain's subdomains known?Relevant Wrappers:get_destination_by_name,get_destination_for_secflow,get_subdomain_details_by_name8. Get Metadata about a BehaviorEndpoint URL:https://api.seclarity.io/sec/v1.0/behaviors/<flowid>Returns any metadata we know for this particular flow category to this Destination. Included metadata:TitleDescriptionRelevanceTagsUse Cases:Has someone tagged this with anImpacttag ofCredentialsEntered?Is this Behavior to this site indicative of a domain being parked?Is this Behavior known to be a Microsoft portal loading?Relevant Wrapper:get_behavior_for_secflow9. Get Metadata about an EventEndpoint URL:https://api.seclarity.io/sec/v1.0/events/<eventid>Returns any metadata we know for this particular Event (made up of two or more Behaviors). Included metadata:TitleDescriptionRelevanceTagsUse Cases:Is this Event known to be associated with a link click on a URL Shortener?Has someone tagged this with aThreattag ofPhishing?Is this Event indicative of a domain being parked?Relevant Wrapper:get_event_for_secflowOther Useful InformationHelper FunctionsThewrappersmodule contains several helper functions to make it easier to perform common actions with the platform more easily.get_aggregated_data_for_samplewraps the API endpoints for public and private samples to return data identically, since the endpoints provide data differently.get_uuid_for_uploaded_samplemakes it easy to get back either the public or private UUID for a sample. Samples that are public have both a public and a private UUID, while those that are private have only the latter. All later sample analysis requires one of these UUIDs.wait_for_sample_processingpolls the platform to identify when the data is ready to be reviewed. A sample will generally take somewhere between 30 and 90 seconds to be processed by the system (depending on load, size of sample, etc...).Supported File FormatsNetworkSage currently supports uploading the following files (which will be converted into our Secflow format):PCAPPCAPNGZeek (conn.log and dns.log)SecflowIf you have a format that you'd like us to support, please review ourFAQsand contactsupport at seclarity [.] io.Getting InvolvedWe havea lotof plans to change the face of security. If you want to be involved as a contributor or to be a part of the community we're building, we highly encourage you to join ourSlack!LicenseThis software is provided under the Apache Software License. See the accompanying LICENSE file for more information.