Location#

To be able to create and thereafter interact with a Sensor we first need to ensure there a Location to which we can attach the Sensor. A Location represents a physical or digital location in a given time and network zone belonging to a specific Customer.

More concretely, Locations are used to have a more granular understanding of customer topology, than just that “event X happened at customer Y”.

By placing sensors in different locations, you will see where in the customers network the event was observed (note: the location of the SENSOR is not necessarily the same as the location of the source or destination of the event).

Events placed into different locations will also NOT be aggregated together by Argus (in realtime), so observing the same event in multiple locations may give the analyst an understanding of how the event has flowed through the customer network.

Locations are normally customer specific. The granularity of the customer locations is up to the implementation project; some customers are more on “continent” level locations, while other customers are “DC” level or even “rack/zone” level. What makes the most sense depends on how our installation at the customer looks, if we have visibility in many different locations at the customer, a more fine-grained location setup may be more suitable.

Having locations on each event, this also allows us to show/query for events by location, and show statistics on events by location.

For small installations, Location is not really relevant, so we tend to only use very general zones such as “External”, “Internal” or “DMZ”. To avoid recreating the same locations over and over again, we have defined these as “global locations”, which are reusable across customers.

Create a Location#

To create a Location POST a AddLocationRequest to the base URL:

    curl -X POST "https://api.mnemonic.no/sensors/v1/location" -H "accept: application/json" -H "Content-Type: application/json" -H "Argus-API-Key: my/api/key" 
    -d '{ 
        "name": "location1",
        "shortName": "l1",
        "networkZone": "INTERNAL",
        "customerID": 1,
        "timeZoneDescription": "Europe/Oslo"
    }'

For the request to be successful:

  • The user must have the addLocation or addGlobalLocation permission depending on the Location’s customer, a role that grants it, or belong to a group with said permission

  • The Customer for whom we want to create the Sensor must exist

  • The AddLocationRequest must be valid

    • The short name must be unique

    • The timezone must exist

Get a Location#

To get a Location append the Location’s shortname or ID to the base URL:

curl -X GET "https://api.mnemonic.no/sensors/v1/location/{idOrShortname}" -H "Argus-API-Key: my/api/key"

For the request to be successful

  • The user must have the viewLocations or viewGlobalLocations permission depending on the Location’s customer, a role that grants it, or belong to a group with said permission

  • The Location must exist

Update a Location#

To update a Location PUT an UpdateLocationRequest to the Location’s path:

    curl -X PUT "https://api.mnemonic.no/sensors/v1/location/{idOrShortname}" -H "accept: application/json" -H "Content-Type: application/json" -H "Argus-API-Key: my/api/key" 
    -d '{ 
        "name": "newlocation1",
        "shortName": "newl1",
        "networkZone": "DMZ",
        "timeZoneDescription": "Europe/London"
    }'

For the request to be successful:

  • The user must have the updateLocation or updateGlobalLocation permission depending on the Location’s customer, a role that grants it, or belong to a group with said permission

  • The Location must exist

  • The UpdateLocationRequest must be valid

    • timezone

    • name

    • shortname

Delete a Location#

To delete a Location submit a DELETE request to the Location’s path:

curl -X DELETE "https://api.mnemonic.no/sensors/v1/location/{idOrShortname}" -H "Argus-API-Key: my/api/key"

For the request to be successful:

  • The user must have the removeLocation or removeGlobalLocation permissions depending on the Location’s customer, a role that grants it or belong to a group with said permission

  • The Location must exist