Identity-Based Microsegmentation Guide
LAST UPDATED: June 23, 2021

Core resources

core

Comment

Represents a comment from a user.

Attributes

claims

Type: []string

The claims of the author.

content

Type: string

The content of the comment.

date

Type: time

The date of the comment.

DiscoveryMode

(Deprecated) When discovery mode is enabled, all flows are accepted. Flows which do not match an existing network policy will be represented by a dotted line in your Platform view.

Example

{
  "propagate": false
}

Relations

GET /discoverymode

(Deprecated) Returns the list of discovery modes.

POST /discoverymode

(Deprecated) Deploy the discovery mode assets onto the specified namespace.

DELETE /discoverymode/:id

(Deprecated) Remove the discovery mode assets with the given import reference ID.

GET /discoverymode/:id

(Deprecated) Retrieve the discovery mode with the given import reference ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

propagate

Type: boolean

Propagates the policy to all of its children.

Export

Allows you to obtain a JSON object containing policies and other objects from a given namespace. You can then import this JSON object into a different namespace.

Example

{
  "identities": [
    "externalnetworks",
    "networkaccesspolicies"
  ],
  "label": "my-import-name"
}

Relations

POST /export

Exports all policies and related objects of a namespace.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.

Attributes

APIVersion [autogenerated,read_only]

Type: integer

Version of the Microsegmentation Console API used for the exported data.

data [autogenerated]

Type: map[string][]map[string]interface{}

List of all exported data.

identities

Type: []string

The list of identities to export.

label

Type: string

Allows you to define a unique label for this export. When importing the content of the export, this label will be added as a tag that will be used to recognize imported object in a later import.

Hit

This API allows to retrieve a generic hit counter for a given object.

Example

{
  "name": "counter",
  "targetIdentity": "networkaccesspolicy"
}

Relations

GET /hits

Retrieve a matching hit.

Parameters:

  • name (string): The name of the counter.
  • targetID (string): The ID of the object associated to the counter.
  • targetIdentity (string): The identity of the object associated to the counter.

Mandatory Parameters

(name and targetID and targetIdentity) or (targetID and targetIdentity)

POST /hits

Manage hits.

Parameters:

  • reset (boolean): If set the hit will reset to 0.

Attributes

name [required]

Type: string

name of the counter.

Default value:

"counter"
targetID

Type: string

The ID of the referenced object..

targetIdentity [required]

Type: string

The identity of the referenced object.

value [read_only]

Type: integer

The value of the hit.

Import

Imports an export of policies and related objects into the namespace.

Example

{
  "data": {
    "externalnetworks": [
      {
        "associatedTags": [
          "ext:net=tcp"
        ],
        "description": "Represents all TCP traffic on any port",
        "entries": [
          "0.0.0.0/0"
        ],
        "name": "all-tcp",
        "servicePorts": [
          "tcp/1:65535"
        ]
      },
      {
        "associatedTags": [
          "ext:net=udp"
        ],
        "description": "Represents all UDP traffic on any port",
        "entries": [
          "0.0.0.0/0"
        ],
        "name": "all-udp",
        "servicePorts": [
          "udp/1:65535"
        ]
      }
    ],
    "networkaccesspolicies": [
      {
        "action": "Allow",
        "description": "Allows all communication from pu to pu, tcp and udp",
        "logsEnabled": true,
        "name": "allow-all-communication",
        "object": [
          [
            "$identity=processingunit"
          ],
          [
            "ext:net=tcp"
          ],
          [
            "ext:net=udp"
          ]
        ],
        "subject": [
          [
            "$identity=processingunit"
          ]
        ]
      }
    ]
  },
  "mode": "Import"
}

Relations

POST /import

Imports data from a previous export.

Attributes

data [required]

Type: export

Data to import.

mode

Type: enum(ReplacePartial | Import | Remove)

How to import the data: ReplacePartial, Import (default), or Remove. ReplacePartial is deprecated. Use Import instead. While you can use ReplacePartial it will be interpreted as Import.

Default value:

"Import"

ImportReference

Allows you to import and keep a reference.

Example

{
  "constraint": "Unrestricted",
  "data": {
    "externalnetworks": [
      {
        "associatedTags": [
          "ext:net=tcp"
        ],
        "description": "Represents all TCP traffic on any port",
        "entries": [
          "0.0.0.0/0"
        ],
        "name": "all-tcp",
        "servicePorts": [
          "tcp/1:65535"
        ]
      },
      {
        "associatedTags": [
          "ext:net=udp"
        ],
        "description": "Represents all UDP traffic on any port",
        "entries": [
          "0.0.0.0/0"
        ],
        "name": "all-udp",
        "servicePorts": [
          "udp/1:65535"
        ]
      }
    ],
    "networkaccesspolicies": [
      {
        "action": "Allow",
        "description": "Allows all communication from pu to pu, tcp and udp",
        "logsEnabled": true,
        "name": "allow-all-communication",
        "object": [
          [
            "$identity=processingunit"
          ],
          [
            "ext:net=tcp"
          ],
          [
            "ext:net=udp"
          ]
        ],
        "subject": [
          [
            "$identity=processingunit"
          ]
        ]
      }
    ]
  },
  "name": "the name",
  "protected": false
}

Relations

GET /importreferences

Retrieves the list of import references.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /importreferences

Imports data from a previous export and keep a reference.

DELETE /importreferences/:id

Deletes the object with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /importreferences/:id

Retrieves the object with the given ID.

GET /recipes/:id/importreferences

Returns the list of import references that depend on a recipe.

POST /recipes/:id/importreferences

Create an import request for the given recipe.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

claims [autogenerated,read_only]

Type: []string

Contains the claims of the client that performed the import.

constraint

Type: enum(Unrestricted | Unique | NamespaceUnique)

Define the import constraint. If Unrestricted, import can be deployed multiple times. If Unique, only one import is allowed in the current namespace and its child namespaces. If NamespaceUnique, only one import is allowed in the current namespace.

Default value:

"Unrestricted"
createTime [autogenerated,read_only]

Type: time

Creation date of the object.

data [required]

Type: export

Data to import.

description [max_length=1024]

Type: string

Description of the object.

label [autogenerated]

Type: string

Label used for the imported data.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

protected

Type: boolean

Defines if the object is protected.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

ImportRequest

Allows you to send an import request to create objects to a namespace where the requester doesn’t normally have the permission to do so (other than creating import requests).

The requester must have the permission to create the request in their namespace and the target namespace.

When the request is created, the status is set to Draft. The requester can edit the content as much as desired. When ready to send the request, update the status to Submitted. The request will then be moved to the target namespace. At that point nobody can edit the content of the requests other than adding comments.

The requestee will now see the request, and will either

  • Set the status as Approved. This will create the objects in the target namespace.

  • Set the status as Rejected. The request cannot be edited anymore and can be deleted.

  • Set the status back as Draft. The request will go back to the requester namespace so that the requester can make changes. Once the change are ready, the requester will set back the status as Submitted.

The data format is the same as Export.

Example

{
  "data": {
    "networkaccesspolicies": [
      {
        "action": "Allow",
        "description": "Allows Acme to access service A",
        "logsEnabled": true,
        "name": "allow-acme",
        "object": [
          [
            "$identity=processingunit",
            "$namespace=/acme/prod",
            "app=query"
          ]
        ],
        "subject": [
          [
            "$identity=processingunit",
            "app=partner-data"
          ]
        ]
      }
    ]
  },
  "protected": false,
  "requesterClaims": [
    "@auth:realm=vince",
    "@auth:account=acme"
  ],
  "status": "Draft",
  "targetNamespace": "/acme/prod"
}

Relations

GET /importrequests

Retrieves the list of import requests.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /importrequests

Creates a new import request.

DELETE /importrequests/:id

Delete an existing import request.

GET /importrequests/:id

Retrieve a single existing import request.

PUT /importrequests/:id

Update an existing import request.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

comment

Type: string

A new comment that will be added to commentFeed.

commentFeed [autogenerated,read_only]

Type: []comment

List of comments that have been added to that request.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

data [required]

Type: map[string][]map[string]interface{}

Data to import.

description [max_length=1024]

Type: string

Description of the object.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

protected

Type: boolean

Defines if the object is protected.

requesterClaims [autogenerated,read_only]

Type: []string

The identity claims of the requester; populated by the Microsegmentation Console.

requesterNamespace [autogenerated,read_only]

Type: string

The namespace from which the request originated; populated by the Microsegmentation Console.

status

Type: enum(Draft | Submitted | Approved | Rejected)

Allows the content to be changed. Submitted: the request moves to the target namespace for approval. Approved: the data will be created immediately. Rejected: the request cannot be changed anymore and can be deleted.

Default value:

"Draft"
targetNamespace [required,creation_only]

Type: string

The namespace where the request will be sent. The requester can set any namespace but needs to have an authorization to post the request in that namespace.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

Poke

When available, poke can be used to update various information about the parent. For instance, for enforcers, poke will be used as the heartbeat.

Relations

GET /enforcers/:id/poke

Sends a poke empty object. This is used to ensure a enforcer is up and running.

Parameters:

  • cpuload (float): Deprecated.
  • enforcementStatus (enum(Failed | Inactive | Active)): If set, changes the enforcement status of the enforcer along with the poke.
  • forceFullPoke (boolean): If set, it will trigger a full poke (slower).
  • memory (integer): Deprecated.
  • processes (integer): Deprecated.
  • sessionClose (boolean): If set, terminates a session for a enforcer.
  • sessionID (string): If set, sends the current session ID of a enforcer.
  • status (enum(Registered | Connected | Disconnected)): If set, changes the status of the enforcer along with the poke.
  • ts (time): time of report. If not set, local server time will be used.
  • version (string): If set, version of the current running enforcer.
  • zhash (integer): Can be set to help Microsegmentation Console target the correct shard where the enforcer is stored.
GET /processingunits/:id/poke

Sends a poke empty object. This will send a snapshot of the processing unit to the time series database.

Parameters:

  • enforcementStatus (enum(Failed | Inactive | Active)): If set, changes the enforcement status of the processing unit alongside with the poke.
  • forceFullPoke (boolean): If set, it will trigger a full poke (slower).
  • notify (boolean): Can be sent to trigger a ProcessingUnitRefresh event that will be handled by the enforcer. If this is set, all other additional parameters will be ignored.
  • status (enum(Initialized | Paused | Running | Stopped)): If set, changes the status of the processing unit alongside with the poke.
  • ts (time): time of report. If not set, local server time will be used.
  • zhash (integer): Can be set to help backend target the correct shard where the processing unit is stored.

PolicyRenderer

Allows you to render policies of a given type for a given set of tags.

Example

{
  "processMode": "Subject",
  "tags": [
    "a=a",
    "b=b"
  ],
  "type": "APIAuthorization"
}

Relations

POST /policyrenderers

Render a policy of a given type for a given set of tags.

Attributes

policies [autogenerated,read_only]

Type: []policyrule

List of policies rendered for the given set of tags.

processMode

Type: enum(Subject | Object)

Subject (default): Set if the processMode should use the subject. Object: Set if the processMode should use the object. This only has effect when rendering an SSH authorization for now.

Default value:

"Subject"
tags [required]

Type: []string

List of tags of the object to render the hook for.

type [required]

Type: enum(APIAuthorization | EnforcerProfile | File | Hook | Infrastructure | NamespaceMapping | Network | ProcessingUnit | Quota | Syscall | TokenScope | SSHAuthorization | UserAccess)

Type of policy to render.

Perform a full text search on the database.

Relations

Perform a full text search on the database.

Parameters:

  • q (string): search query.

Mandatory Parameters

q

Attributes

object [autogenerated,read_only]

Type: object

Contains the matched object.

objectID [autogenerated,read_only]

Type: string

Contains the ID of the match.

objectIdentity [autogenerated,read_only]

Type: string

Contains the identity of the match.

objectNamespace [autogenerated,read_only]

Type: string

Contains the namespace of the match.

score [autogenerated,read_only]

Type: float

Contains the score of the match.

core/accessiblenamespace

AccessibleNamespace

An Accessible Namespace represents a namespace that can be accessed by a given user.

Relations

GET /accessiblenamespaces

Retrieves the list of accessible namespaces.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.

Attributes

name [read_only]

Type: string

Name of the namespace that is accessible.

core/account

Account

Allows you to view and manage basic information about your account like your name, password, and whether or not two-factor authentication is enabled.

Example

{
  "OTPEnabled": false,
  "SSHCARenew": false,
  "accessEnabled": false,
  "company": "Acme",
  "email": "user@acme.com",
  "firstName": "John",
  "lastName": "Doe",
  "localCARenew": false,
  "name": "acme"
}

Relations

GET /accounts

Retrieves all accounts. This is a private API that can only be done by the system.

Parameters:

  • name (string): internal parameters.
  • status (string): internal parameters.
  • q (string): Filtering query. Consequent q parameters will form an or.
POST /accounts

Creates a new account.

DELETE /accounts/:id

Deletes the object with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /accounts/:id

Retrieves the object with the given ID.

PUT /accounts/:id

Updates the object with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

OTPEnabled

Type: boolean

Enable or disable two-factor authentication.

OTPQRCode [autogenerated,read_only]

Type: string

Returns the base64-encoded QR code for setting up two-factor authentication.

SSHCA [autogenerated,read_only]

Type: string

Holds the SSH certificate authority used by the account namespace.

SSHCARenew

Type: boolean

Set to true to renew the SSH certificate authority of the account namespace.

accessEnabled

Type: boolean

Defines if the account holder should have access to the system.

activationToken [autogenerated]

Type: string

Contains the activation token.

associatedPlanKey [creation_only]

Type: string

Contains the plan key associated with this account.

company

Type: string

Company of the account user.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

email [required]

Type: string

Email of the account holder.

firstName

Type: string

First name of the account user.

lastName

Type: string

Last name of the account user.

localCA [autogenerated,read_only]

Type: string

The certificate authority used by this namespace.

localCARenew

Type: boolean

Set to true to renew the local certificate authority of the account namespace.

name [required,creation_only,format=^[^\*\=]*$]

Type: string

Name of the account.

newPassword

Type: string

New password for the account. If set the previous password must be given through the property password.

password

Type: string

Password for the account.

reCAPTCHAKey [creation_only]

Type: string

Contains the completely automated public Turing test (CAPTCHA) validation if reCAPTCHA is enabled.

status [autogenerated,read_only]

Type: enum(Active | Disabled | Invited | Pending)

Status of the account.

Default value:

"Pending"
updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

Activate

Used to activate a pending account.

Example

{
  "token": "2BB3D52C-DE26-406A-8821-613F102282B0"
}

Relations

GET /activate

Activates a pending account.

Parameters:

  • noRedirect (boolean): If set, do not redirect the request to the web interface.
  • token (string): Activation token.

Mandatory Parameters

token

Attributes

token [creation_only]

Type: string

Contains the activation token.

PasswordReset

Used to reset a Microsegmentation account password.

Example

{
  "password": "NewPassword123@",
  "token": "436676D4-7ECA-4853-A572-0644EE9D89EF"
}

Relations

GET /passwordreset

Sends a link to the account email to reset the password.

Parameters:

  • email (string): Email associated to the account.

Mandatory Parameters

email

POST /passwordreset

Resets the password for an account using the provided link.

Attributes

password [required]

Type: string

Contains the new password.

token [required]

Type: string

Contains the reset password token.

core/authentication

Authn

Verifies if the given token is valid or not. If it is valid it will return the claims of the token.

Relations

GET /authn

Verify the validity of a token. This is deprecated. You should use Create.

Parameters:

  • token (string): token to validate.
POST /authn

Verify the validity of a token.

Attributes

claims [autogenerated,read_only]

Type: _claims

The claims in the token.

token

Type: string

The token to verify. This is only used if a POST request is used.

Issue

Issues a new Microsegmentation token according to given data.

Example

{
  "audience": "aud:*:*:/namespace",
  "metadata": {
    "vinceAccount": "acme",
    "vinceOTP": 665435,
    "vincePassword": "s3cr3t"
  },
  "realm": "Vince",
  "restrictedNamespace": "/namespace",
  "restrictedNetworks": [
    "10.0.0.0/8",
    "127.0.0.1/32"
  ],
  "restrictedPermissions": [
    "@auth:role=enforcer",
    "namespace,post"
  ],
  "validity": "24h"
}

Relations

POST /issue

Issues a new token.

Parameters:

  • asCookie (boolean): If set to true, the token will be delivered in a secure cookie, and not in the response body.
  • token (string): Token to verify.

Attributes

audience

Type: string

If given, the issued token will only be valid for the specified namespace. Refer to JSON Web Token (JWT)RFC 7519. for further information.

claims [autogenerated,read_only]

Type: _claims

The claims in the token. It is only set is the parameter asCookie is given.

data

This attribute is deprecated.

Type: string

Contains additional data. The value depends on the issuer type.

metadata

Type: map[string]interface{}

Contains various additional information. Meaning depends on the realm.

opaque

Type: map[string]string

Opaque data that will be included in the issued token.

quota

Type: integer

Restricts the number of times the issued token can be used.

realm [required]

Type: enum(AWSSecurityToken | Certificate | Google | LDAP | Vince | GCPIdentityToken | AzureIdentityToken | OIDC | SAML | AporetoIdentityToken | PCIdentityToken)

The authentication realm. This will define how to verify credentials from internal or external source of authentication.

restrictedNamespace

Type: string

Restricts the namespace where the token can be used.

For instance, if you have have access to /namespace and below, you can tell the policy engine that it should restrict further more to /namespace/child.

Restricting to a namespace you don’t have initially access according to the policy engine has no effect and may end up making the token unusable.

restrictedNetworks

Type: []string

Restricts the networks from where the token can be used. This will reduce the existing set of authorized networks that normally apply to the token according to the policy engine.

For instance, If you have authorized access from 0.0.0.0/0 (by default) or from 10.0.0.0/8, you can ask for a token that will only be valid if used from 10.1.0.0/16.

Restricting to a network that is not initially authorized by the policy engine has no effect and may end up making the token unusable.

restrictedPermissions

Type: []string

Restricts the permissions of token. This will reduce the existing permissions that normally apply to the token according to the policy engine.

For instance, if you have administrative role, you can ask for a token that will tell the policy engine to reduce the permission it would have granted to what is given defined in the token.

Restricting to some permissions you don’t initially have according to the policy engine has no effect and may end up making the token unusable.

token [autogenerated,read_only]

Type: string

The token to use for the registration.

validity

Type: string

Configures the maximum length of validity for a token, using Golang duration syntax. If it is bigger than the configured max validity, it will be capped. Default: 24h.

Default value:

"24h"

LDAPProvider

Allows you to declare a generic LDAP provider that can be used in exchange for a Midgard token.

Example

{
  "address": "ldap.company.com",
  "baseDN": "dc=universe,dc=io",
  "bindDN": "cn=readonly,dc=universe,dc=io",
  "bindPassword": "s3cr3t",
  "bindSearchFilter": "uid={USERNAME}",
  "certificateAuthority": "-----BEGIN CERTIFICATE-----
MIIBPzCB5qADAgECAhEAwbx3c+QW24ePXyD94geytzAKBggqhkjOPQQDAjAPMQ0w
CwYDVQQDEwR0b3RvMB4XDTE5MDIyMjIzNDA1MFoXDTI4MTIzMTIzNDA1MFowDzEN
MAsGA1UEAxMEdG90bzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJi6CwRDeKks
Xb3pDEslmFGR7k9Aeh5RK+XmdqKKPGb3NQWEFPGolnqOR34iVuf7KSxTuzaaVWfu
XEa94faUQEqjIzAhMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MAoG
CCqGSM49BAMCA0gAMEUCIQD+nL9RF9EvQXHyYuJ31Lz9yWd9hsK91stnpAs890gS
/AIgQIKjBBpiyQNZZWso5H04qke9QYMVPegiQQufFFBj32c=
-----END CERTIFICATE-----",
  "connSecurityProtocol": "InbandTLS",
  "default": false,
  "name": "the name",
  "protected": false,
  "subjectKey": "uid"
}

Relations

GET /ldapproviders

Retrieves the list of the namespace LDAP providers.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /ldapproviders

Creates a new LDAP provider.

DELETE /ldapproviders/:id

Deletes the provider with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /ldapproviders/:id

Retrieves the provider with the given ID.

PUT /ldapproviders/:id

Updates the provider with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

address [required]

Type: string

Contains the fully qualified domain name (FQDN) or IP address of the private LDAP server.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

baseDN [required]

Type: string

Contains the base distinguished name (DN) to use for LDAP queries. Example: dc=example,dc=com.

bindDN [required]

Type: string

Contains the DN to use to bind to the LDAP server. Example: cn=admin,dc=example,dc=com.

bindPassword [required]

Type: string

Contains the password to be used with the bindDN to authenticate to the LDAP server.

bindSearchFilter

Type: string

The filter to use to locate the relevant user accounts. For Windows-based systems, the value may be sAMAccountName={USERNAME}. For Linux and other systems, the value may be uid={USERNAME}.

Default value:

"uid={USERNAME}"
certificateAuthority

Type: string

Can be left empty if the LDAP server’s certificate is signed by a public, trusted certificate authority. Otherwise, include the public key of the certificate authority that signed the LDAP server’s certificate.

connSecurityProtocol

Type: enum(TLS | InbandTLS)

Specifies the connection type for the LDAP provider. TLS or InbandTLS (default).

Default value:

"InbandTLS"
createTime [autogenerated,read_only]

Type: time

Creation date of the object.

default

Type: boolean

If set, this will be the default LDAP provider. There can be only one default provider in your account. When logging in with LDAP, if no provider name is given, the default will be used.

description [max_length=1024]

Type: string

Description of the object.

ignoredKeys

Type: []string

A list of keys that must not be imported into a Microsegmentation authorization. If includedKeys is also set, and a key is in both lists, the key will be ignored.

includedKeys

Type: []string

A list of keys that must be imported into a Microsegmentation authorization. If ignoredKeys is also set, and a key is in both lists, the key will be ignored.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

protected

Type: boolean

Defines if the object is protected.

subjectKey

Type: string

The key to be used to populate the subject of the Midgard token. If you want to use the user as a subject, for Windows-based systems you may use sAMAccountName. For Linux and other systems, you may wish to use uid (default). You can also use any alternate key.

Default value:

"uid"
updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

Logout

Perform logout operations. This is only used to unset the secure cookie token for now.

Relations

GET /logout

Performs a logout operation.

OIDCProvider

Allows you to declare a generic OpenID Connect (OIDC) provider that can be used in exchange for a Midgard token.

Example

{
  "certificateAuthority": "-----BEGIN CERTIFICATE-----
MIIBczCCARigAwIBAgIRALD3Vz81Pq10g7n4eAkOsCYwCgYIKoZIzj0EAwIwJjEN
MAsGA1UEChMEQWNtZTEVMBMGA1UEAxMMQWNtZSBSb290IENBMB4XDTE4MDExNzA2
NTM1MloXDTI3MTEyNjA2NTM1MlowGDEWMBQGA1UEAxMNY2xhaXJlLWNsaWVudDBZ
MBMGByqGSM49AgEGCCqGSM49AwEHA0IABOmzPJj+t25T148eQH5gVrZ7nHwckF5O
evJQ3CjSEMesjZ/u7cW8IBfXlxZKHxl91IEbbB3svci4c8pycUNZ2kujNTAzMA4G
A1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAjAMBgNVHRMBAf8EAjAA
MAoGCCqGSM49BAMCA0kAMEYCIQCjAAmkQpTua0HR4q6jnePaFBp/JMXwTXTxzbV6
peGbBQIhAP+1OR8GFnn2PlacwHqWXHwkvy6CLPVikvgtwEdB6jH8
-----END CERTIFICATE-----",
  "clientID": "6195189841830-0644ee9d89ef0644ee9d89examle.apps.googleusercontent.com",
  "clientSecret": "Ytgbfjtj4652jHDFGls99jF",
  "default": false,
  "endpoint": "https://accounts.google.com",
  "name": "the name",
  "protected": false,
  "scopes": [
    "email",
    "profile"
  ],
  "subjects": [
    "email",
    "profile"
  ]
}

Relations

GET /oidcproviders

Retrieves the list of OIDC providers.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /oidcproviders

Creates a new OIDC provider.

DELETE /oidcproviders/:id

Deletes the provider with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /oidcproviders/:id

Retrieves the provider with the given ID.

PUT /oidcproviders/:id

Updates the provider with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

certificateAuthority

Type: string

Set the CA to use to contact the OIDC server. This is useful when you are using a custom OIDC provider that doesn’t use a trusted CA. Most of the time, you can leave this property empty.

clientID [required]

Type: string

Unique client ID.

clientSecret [required]

Type: string

Client secret associated with the client ID.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

default

Type: boolean

If set, this will be the default OIDC provider. There can be only one default provider in your account. When logging in with OIDC, if no provider name is given, the default will be used.

description [max_length=1024]

Type: string

Description of the object.

endpoint [required]

Type: string

OIDC discovery endpoint.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

parentID [autogenerated,read_only]

Type: string

Contains the parent Microsegmentation account ID.

parentName [autogenerated,read_only]

Type: string

Contains the name of the parent Microsegmentation account.

protected

Type: boolean

Defines if the object is protected.

scopes

Type: []string

List of scopes to allow.

subjects

Type: []string

List of claims that will provide the subject.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

PCCProvider

Allows you to declare a trusted Prisma Cloud Compute (PCC) authentication provider. Microsegmentation will accept JSON web tokens (JWT) from the specified PCC provider.

Example

{
  "certificateAuthority": "-----BEGIN CERTIFICATE-----
MIIBczCCARigAwIBAgIRALD3Vz81Pq10g7n4eAkOsCYwCgYIKoZIzj0EAwIwJjEN
MAsGA1UEChMEQWNtZTEVMBMGA1UEAxMMQWNtZSBSb290IENBMB4XDTE4MDExNzA2
NTM1MloXDTI3MTEyNjA2NTM1MlowGDEWMBQGA1UEAxMNY2xhaXJlLWNsaWVudDBZ
MBMGByqGSM49AgEGCCqGSM49AwEHA0IABOmzPJj+t25T148eQH5gVrZ7nHwckF5O
evJQ3CjSEMesjZ/u7cW8IBfXlxZKHxl91IEbbB3svci4c8pycUNZ2kujNTAzMA4G
A1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAjAMBgNVHRMBAf8EAjAA
MAoGCCqGSM49BAMCA0kAMEYCIQCjAAmkQpTua0HR4q6jnePaFBp/JMXwTXTxzbV6
peGbBQIhAP+1OR8GFnn2PlacwHqWXHwkvy6CLPVikvgtwEdB6jH8
-----END CERTIFICATE-----",
  "default": false,
  "endpoint": "https://my.pcc.acme.com",
  "name": "the name",
  "protected": false
}

Relations

GET /pccproviders

Retrieves the list of the PCC providers.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /pccproviders

Creates a new PCC provider.

DELETE /pccproviders/:id

Deletes the provider with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /pccproviders/:id

Retrieves the provider with the given ID.

PUT /pccproviders/:id

Updates the provider with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

certificateAuthority

Type: string

Set the CA to use to contact the PCC Console in case it uses a non widely trusted certificate authority.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

default

Type: boolean

If set, this will be the default PCC provider. There can be only one default provider in your account. When logging in with PCC, if no provider name is given, the default will be used.

endpoint [required]

Type: string

The URL of the PCC service. It must use HTTPS.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

protected

Type: boolean

Defines if the object is protected.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

SAMLProvider

Allows you to declare a generic SAML provider that can be used in exchange for a Midgard token.

Example

{
  "IDPCertificate": "-----BEGIN CERTIFICATE REQUEST-----
MIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV
BAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln
aUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo
wp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c
1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI
WDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ
wIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR
BPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ
KoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D
hJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY
Q4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/
ZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn
29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2
97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=
-----END CERTIFICATE REQUEST-----",
  "IDPIssuer": "https://accounts.google.com/o/saml2/idp?idpid=AbDcef123",
  "IDPURL": "https://accounts.google.com/o/saml2/idp?idpid=AbDcef123",
  "default": false,
  "name": "the name",
  "protected": false,
  "subjects": [
    "email",
    "profile"
  ]
}

Relations

GET /samlproviders

Retrieves the list of the namespace SAML providers.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /samlproviders

Creates a new LDAP provider.

DELETE /samlproviders/:id

Deletes the provider with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /samlproviders/:id

Retrieves the provider with the given ID.

PUT /samlproviders/:id

Updates the provider with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

IDPCertificate

Type: string

Identity provider certificate in PEM format.

IDPIssuer

Type: string

Identity Provider Issuer (also called Entity ID).

IDPMetadata

Type: string

Pass some XML data containing the IDP metadata that can be used for automatic configuration. If you pass this attribute, every other one will be overwritten with the data contained in the metadata file.

IDPURL

Type: string

URL of the identity provider.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

default

Type: boolean

If set, this will be the default SAML provider. There can be only one default provider in your account. When logging in with SAML, if no provider name is given, the default will be used.

description [max_length=1024]

Type: string

Description of the object.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

protected

Type: boolean

Defines if the object is protected.

subjects

Type: []string

List of claims that will provide the subject.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

core/billing

Plan

Contains the various billing plans available.

Relations

GET /plans

Retrieves the list of plans.

GET /plans/:id

Retrieves the plan with the given ID.

Attributes

description [autogenerated,read_only]

Type: string

Contains the description of the plan.

key [autogenerated,read_only]

Type: string

Contains the key identifier of the plan.

name [autogenerated,read_only]

Type: string

Contains the name of the plan.

core/enforcer

CounterReport

Post a new counter tracing report.

Example

{
  "enforcerID": "xxxx-xxx-xxxx",
  "enforcerNamespace": "/my/namespace",
  "namespace": "/my/namespace",
  "processingUnitID": "xxx-xxx-xxx",
  "processingUnitNamespace": "/my/namespace",
  "timestamp": "2018-06-14T23:10:46.420397985Z"
}

Relations

POST /counterreports

Create a counter report.

Attributes

AckInUnknownState

Type: integer

Counter for sending FIN ACK received in unknown connection state.

AckInvalidFormat

Type: integer

Counter for ACK packet dropped because of invalid format.

AckRejected

Type: integer

Counter for ACK packets rejected as per policy.

AckSigValidationFailed

Type: integer

Counter for ACK packet dropped because signature validation failed.

AckTCPNoTCPAuthOption

Type: integer

Counter for TCP authentication option not found.

ConnectionsProcessed

Type: integer

Counter for connections processed.

ContextIDNotFound

Type: integer

Counter for unable to find ContextID.

DroppedExternalService

Type: integer

Counter for no ACLs found for external services. Dropping application SYN packet.

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

InvalidConnState

Type: integer

Counter for invalid connection state.

InvalidNetState

Type: integer

Counter for invalid net state.

InvalidProtocol

Type: integer

Counter for invalid protocol.

InvalidSynAck

Type: integer

Counter for processing unit is already dead - drop SYN ACK packet.

MarkNotFound

Type: integer

Counter for processing unit mark not found.

NetSynNotSeen

Type: integer

Counter for network SYN packet was not seen.

NoConnFound

Type: integer

Counter for no context or connection found.

NonPUTraffic

Type: integer

Counter for traffic that belongs to a non-processing unit process.

OutOfOrderSynAck

Type: integer

Counter for SYN ACK for flow with processed FIN ACK.

PortNotFound

Type: integer

Counter for port not found.

RejectPacket

Type: integer

Counter for reject the packet as per policy.

ServicePostprocessorFailed

Type: integer

Counter for post service processing failed for network packet.

ServicePreprocessorFailed

Type: integer

Counter for network packets that failed preprocessing.

SynAckBadClaims

Type: integer

Counter for SYN ACK packet dropped because of bad claims.

SynAckClaimsMisMatch

Type: integer

Counter for SYN ACK packet dropped because of encryption mismatch.

SynAckDroppedExternalService

Type: integer

Counter for SYN ACK from external service dropped.

SynAckInvalidFormat

Type: integer

Counter for SYN ACK packet dropped because of invalid format.

SynAckMissingClaims

Type: integer

Counter for SYN ACK packet dropped because of no claims.

SynAckMissingToken

Type: integer

Counter for SYN ACK packet dropped because of missing token.

SynAckNoTCPAuthOption

Type: integer

Counter for TCP authentication option not found.

SynAckRejected

Type: integer

Counter for dropping because of reject rule on transmitter.

SynDroppedInvalidFormat

Type: integer

Counter for SYN packet dropped because of invalid format.

SynDroppedInvalidToken

Type: integer

Counter for SYN packet dropped because of invalid token.

SynDroppedNoClaims

Type: integer

Counter for SYN packet dropped because of no claims.

SynDroppedTCPOption

Type: integer

Counter for TCP authentication option not found.

SynRejectPacket

Type: integer

Counter for SYN packet dropped due to policy.

SynUnexpectedPacket

Type: integer

Counter for received SYN packet from unknown processing unit.

TCPAuthNotFound

Type: integer

Counter for TCP authentication option not found.

UDPAckInvalidSignature

Type: integer

Counter for UDP ACK packet dropped due to an invalid signature.

UDPConnectionsProcessed

Type: integer

Counter for number of processed UDP connections.

UDPDropContextNotFound

Type: integer

Counter for dropped UDP data packets with no context.

UDPDropFin

Type: integer

Counter for dropped UDP FIN handshake packets.

UDPDropInNfQueue

Type: integer

Counter for dropped UDP in NfQueue.

UDPDropNoConnection

Type: integer

Counter for dropped UDP data packets with no connection.

UDPDropPacket

Type: integer

Counter for dropped UDP data packets.

UDPDropQueueFull

Type: integer

Counter for dropped UDP queue full.

UDPDropSynAck

Type: integer

Counter for dropped UDP SYN ACK handshake packets.

UDPInvalidNetState

Type: integer

Counter for UDP packets received in invalid network state.

UDPPostProcessingFailed

Type: integer

Counter for UDP packets failing postprocessing.

UDPPreProcessingFailed

Type: integer

Counter for UDP packets failing preprocessing.

UDPRejected

Type: integer

Counter for UDP packets dropped due to policy.

UDPSynAckDropBadClaims

Type: integer

Counter for UDP SYN ACK packets dropped due to bad claims.

UDPSynAckMissingClaims

Type: integer

Counter for UDP SYN ACK packets dropped due to missing claims.

UDPSynAckPolicy

Type: integer

Counter for UDP SYN ACK packets dropped due to bad claims.

UDPSynDrop

Type: integer

Counter for dropped UDP SYN transmits.

UDPSynDropPolicy

Type: integer

Counter for dropped UDP SYN policy.

UDPSynInvalidToken

Type: integer

Counter for dropped UDP FIN handshake packets.

UDPSynMissingClaims

Type: integer

Counter for UDP SYN packet dropped due to missing claims.

UnknownError

Type: integer

Counter for unknown error.

connectionsAnalyzed

Type: integer

Non-zero counter indicates analyzed connections for unencrypted, encrypted, and packets from endpoint applications with the TCP Fast Open option set. These are not dropped counter.

connectionsDropped

Type: integer

Non-zero counter indicates dropped connections because of invalid state, non-processing unit traffic, or out of order packets.

connectionsExpired

Type: integer

Non-zero counter indicates expired connections because of response not being received within a certain amount of time after the request is made.

droppedPackets

Type: integer

Non-zero counter indicates dropped packets that did not hit any of our iptables rules and queue drops.

encryptionFailures

Type: integer

Non-zero counter indicates encryption processing failures of data packets.

enforcerID [required]

Type: string

Identifier of the enforcer sending the report.

enforcerNamespace

This attribute is deprecated.

Type: string

Namespace of the enforcer sending the report. This field is deprecated. Use the ‘namespace’ field instead. field instead.

externalNetworkConnections

Type: integer

Non-zero counter indicates connections going to and from external networks. These may be drops or allowed counters.

namespace [read_only]

Type: string

Namespace of the enforcer sending the report.

policyDrops

Type: integer

Non-zero counter indicates packets dropped due to a reject policy.

processingUnitID

Type: string

PUID is the ID of the processing unit reporting the counter.

processingUnitNamespace

Type: string

Namespace of the processing unit reporting the counter.

timestamp

Type: time

Timestamp is the date of the report.

tokenDrops

Type: integer

Non-zero counter indicates packets rejected due to anything related to token creation/parsing failures.

Enforcer

Contains all parameters associated with a registered enforcer. The object is mainly maintained by the enforcers themselves. Users can read the object in order to understand the current status of the enforcers.

Example

{
  "FQDN": "server1.domain.com",
  "certificateRequest": "-----BEGIN CERTIFICATE REQUEST-----
MIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV
BAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln
aUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo
wp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c
1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI
WDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ
wIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR
BPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ
KoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D
hJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY
Q4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/
ZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn
29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2
97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=
-----END CERTIFICATE REQUEST-----",
  "collectInfo": false,
  "detectedHostModeContainers": false,
  "enforcementStatus": "Inactive",
  "lastCollectionID": "xxx-xxx-xxx-xxx -",
  "logLevel": "Info",
  "logLevelDuration": "10s",
  "machineID": "3F23E8DF-C56D-45CF-89B8-A867F3956409",
  "migrationStatus": "None",
  "name": "the name",
  "operationalStatus": "Registered",
  "protected": false
}

Relations

GET /enforcers

Retrieves the list of enforcers.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /enforcers

Creates a new enforcer.

DELETE /enforcers/:id

Deletes the enforcer with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /enforcers/:id

Retrieves the enforcer with the given ID.

PUT /enforcers/:id

Updates the enforcer with the given ID.

GET /auditprofilemappingpolicies/:id/enforcers

Returns the list of enforcers that are affected by this mapping.

GET /enforcerprofilemappingpolicies/:id/enforcers

Returns the list of enforcers affected by an enforcer profile mapping.

GET /hostservicemappingpolicies/:id/enforcers

Returns the list of enforcers that are affected by this mapping.

GET /enforcers/:id/auditprofiles

Returns a list of the audit profiles that must be applied to this enforcer.

GET /enforcers/:id/debugbundles

Retrieves the list of debug bundles.

POST /enforcers/:id/debugbundles

Uploads a debug bundle.

GET /enforcers/:id/enforcerprofiles

Returns the enforcer profile that must be used by a enforcer.

POST /enforcers/:id/enforcerrefreshes

Sends a enforcer refresh command.

GET /enforcers/:id/hostservices

Returns a list of the host services policies that apply to this enforcer.

Parameters:

  • appliedServices (boolean): Valid when retrieved for a given enforcer and returns the applied services.
  • setServices (boolean): Instructs Microsegmentation Console to cache the services that were resolved.
GET /enforcers/:id/poke

Sends a poke empty object. This is used to ensure a enforcer is up and running.

Parameters:

  • cpuload (float): Deprecated.
  • enforcementStatus (enum(Failed | Inactive | Active)): If set, changes the enforcement status of the enforcer along with the poke.
  • forceFullPoke (boolean): If set, it will trigger a full poke (slower).
  • memory (integer): Deprecated.
  • processes (integer): Deprecated.
  • sessionClose (boolean): If set, terminates a session for a enforcer.
  • sessionID (string): If set, sends the current session ID of a enforcer.
  • status (enum(Registered | Connected | Disconnected)): If set, changes the status of the enforcer along with the poke.
  • ts (time): time of report. If not set, local server time will be used.
  • version (string): If set, version of the current running enforcer.
  • zhash (integer): Can be set to help Microsegmentation Console target the correct shard where the enforcer is stored.
GET /enforcers/:id/trustedcas

Returns the list of certificate authorities that should be trusted by this enforcer.

Parameters:

  • type (enum(Any | X509 | SSH)): Type of certificate to get.

Attributes

FQDN [required,creation_only]

Type: string

Contains the fully qualified domain name (FQDN) of the server where the enforcer is running.

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

certificate [autogenerated,read_only]

Type: string

The certificate of the enforcer.

certificateRequest

Type: string

If not empty during a create or update operation, the provided certificate signing request (CSR) will be validated and signed by the Microsegmentation Console, providing a renewed certificate.

collectInfo

Type: boolean

Indicates to the enforcer whether or not it needs to collect information.

collectedInfo

This attribute is deprecated.

Type: map[string]string

Represents the latest information collected by the enforcer.

controller [autogenerated,read_only]

Type: string

The Microsegmentation Console identifier managing this object. This property is mostly useful when federating multiple Microsegmentation Consoles.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

currentVersion

Type: string

The version number of the installed enforcer binary.

description [max_length=1024]

Type: string

Description of the object.

detectedHostModeContainers

Type: boolean

This field indicates whether the enforcer has detected host mode containers.

enforcementStatus

Type: enum(Inactive | Active | Failed)

Status of the enforcement for host services.

Default value:

"Inactive"
lastCollectionID

Type: string

Identifies the last collection.

lastCollectionTime

Type: time

Identifies when the information was collected.

lastMigrationTime

Type: time

Last migration date of the enforcer.

lastSyncTime

Type: time

The time and date of the last heartbeat.

localCA [autogenerated]

Type: string

Contains the initial chain of trust for the enforcer. This value is only given when you retrieve a single enforcer.

logLevel

Type: enum(Info | Debug | Warn | Error | Trace)

Log level of the enforcer.

Default value:

"Info"
logLevelDuration

Type: string

Determines the duration of which the log level will be active, using Golang duration syntax.

Default value:

"10s"
machineID

Type: string

A unique identifier for every machine as detected by the enforcer. It is based on hardware information such as the SMBIOS UUID, MAC addresses of interfaces, or cloud provider IDs.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

migrationStatus

Type: enum(None | Running | Failed)

Defines the migration status.

Default value:

"None"
name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

nextAvailableVersion

Type: string

Defines the next version the enforcer will be migrated to.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

operationalStatus

Type: enum(Registered | Connected | Disconnected | Initialized)

The status of the enforcer.

Default value:

"Registered"
protected

Type: boolean

Defines if the object is protected.

publicToken [autogenerated,read_only]

Type: string

The public token of the server that will be included in the datapath and is signed by the private certificate authority.

startTime

Type: time

The time and date on which this enforcer was started. The enforcer reports this and the value is preserved across disconnects.

subnets

Type: []string

Local subnets of this enforcer.

unreachable [autogenerated,read_only]

Type: boolean

The Microsegmentation Console sets this value to true if it hasn’t heard from the enforcer in the last five minutes.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

EnforcerLog

An enforcer log represents the log collected by an enforcer. Each enforcer log can have partial or complete data. The collectionID is used to aggregate the multipart data into one.

Example

{
  "collectionID": "xxx-xxx-xxx-xxx",
  "enforcerID": "xxx-xxx-xxx-xxx",
  "protected": false
}

Relations

GET /enforcerlog

Retrieves the list of enforcerlogs.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /enforcerlog

Creates a new enforcerlog.

GET /enforcerlog/:id

Retrieves the enforcerlog with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

collectionID [required]

Type: string

Contains the ID of the enforcer log. CollectionID is used to aggregate the multipart data.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

data

Type: string

Represents the data collected by the enforcer.

enforcerID [required]

Type: string

ID of the enforcer.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

page

Type: integer

Number assigned to each log in the increasing order.

protected

Type: boolean

Defines if the object is protected.

title

Type: string

Title of the log.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

EnforcerReport

Post a new enforcer statistics report.

Example

{
  "CPULoad": 10,
  "enforcerID": "xxx-xxx-xxx-xxx",
  "licenseType": "Host",
  "memory": 10000,
  "name": "aporeto-enforcerd-xxx",
  "namespace": "/my/ns",
  "processes": 10,
  "timestamp": "2018-06-14T23:10:46.420397985Z"
}

Relations

POST /enforcerreports

Create an enforcer statistics report.

Attributes

CPULoad

Type: float

Total CPU utilization of the enforcer as a percentage of vCPUs.

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

enforcerID

Type: string

ID of the enforcer.

licenseType [required]

Type: enum(Host | Container)

Type of license for this enforcer.

Default value:

"Host"
memory

Type: integer

Total resident memory used by the enforcer in bytes.

name [required]

Type: string

Name of the enforcer.

namespace [required]

Type: string

Namespace of the enforcer.

processes

Type: integer

Number of active processes of the enforcer.

timestamp [required]

Type: time

Date of the report.

EnforcerTraceReport

Post a new enforcer trace that determines how packets are.

Example

{
  "enforcerID": "5c6cce207ddf1fc159a104bf",
  "enforcerNamespace": "/acme/prod",
  "namespace": "/acme/prod/database",
  "puID": "5c6ccd947ddf1fc159a104b7"
}

Relations

POST /enforcertracereports

Create an enforcer trace report.

Attributes

enforcerID [required]

Type: string

ID of the enforcer where the trace was collected.

enforcerNamespace [required]

Type: string

Namespace of the enforcer where the trace was collected.

namespace [required]

Type: string

Namespace of the processing unit where the trace was collected.

puID [required]

Type: string

ID of the processing unit where the trace was collected.

PacketReport

Post a new packet tracing report.

Example

{
  "destinationPort": 11000,
  "encrypt": false,
  "enforcerID": "xxxx-xxx-xxxx",
  "enforcerNamespace": "/my/namespace",
  "event": "Rcv",
  "mark": 123123,
  "namespace": "/my/namespace",
  "packetID": 12333,
  "protocol": 6,
  "puID": "xxx-xxx-xxx",
  "rawPacket": "abcd",
  "sourcePort": 80,
  "timestamp": "2018-06-14T23:10:46.420397985Z",
  "triremePacket": true
}

Relations

POST /packetreports

Create a packet trace report.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

TCPFlags

Type: integer

Flags are the TCP flags of the packet.

claims

Type: []string

Claims is the list of claims detected for the packet.

destinationIP

Type: string

The destination IP address of the packet.

destinationPort [max_value=65536.000000]

Type: integer

The destination port of a TCP or UDP packet.

dropReason

Type: string

If event is set to Dropped, contains the reason that the packet was dropped. Otherwise empty.

encrypt

Type: boolean

Set to true if the packet was encrypted.

enforcerID [required]

Type: string

Identifier of the enforcer sending the report.

enforcerNamespace [required]

Type: string

Namespace of the enforcer sending the report.

event [required]

Type: enum(Received | Transmitted | Dropped)

The event that triggered the report.

mark

Type: integer

Mark is the mark value of the packet.

namespace [required]

Type: string

Namespace of the processing unit reporting the packet.

packetID

Type: integer

The ID of the IP header of the reported packet.

protocol [max_value=255.000000]

Type: integer

Protocol number.

puID

Type: string

The ID of the processing unit reporting the packet.

rawPacket

Type: string

The first 64 bytes of the packet.

Default value:

"abcd"
sourceIP

Type: string

The source IP address of the packet.

sourcePort [max_value=65536.000000]

Type: integer

The source port of the packet.

timestamp [required]

Type: time

The time-date stamp of the report.

triremePacket

Type: boolean

Set to true if the packet arrived with the Trireme options (default).

Default value:

true

PingPair

Represents a pair of ping probes.

Attributes

request

Type: pingprobe

Contains the request probe information.

response

Type: pingprobe

Contains the response probe information.

PingProbe

Represents the result of a unique ping probe. They are aggregated into a PingResult.

Example

{
  "applicationListening": false,
  "claimsType": [
    "Transmitted"
  ],
  "enforcerID": "xxx-xxx-xxx-xxx",
  "enforcerNamespace": "/my/ns",
  "excludedNetworks": false,
  "isServer": false,
  "payloadSizeType": [
    "Transmitted"
  ],
  "pingID": "xxx-xxx-xxx-xxx",
  "remoteEndpointType": [
    "External"
  ],
  "remoteNamespaceType": [
    "Plain"
  ],
  "targetTCPNetworks": false,
  "type": [
    "Request"
  ]
}

Relations

GET /pingprobes/:id

Retrieves a ping result.

POST /processingunits/:id/pingprobes

Create a ping probe.

Attributes

ACLPolicyAction

Type: string

Action of the ACL policy.

ACLPolicyID

Type: string

ID of the ACL policy.

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

RTT

Type: string

Time taken for a single request-response to complete.

applicationListening

Type: boolean

If true, application responded to the request.

claims

Type: []string

Claims of the processing unit.

claimsType [required]

Type: enum(Transmitted | Received)

Type of claims reported.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

enforcerID [required]

Type: string

ID of the enforcer.

enforcerNamespace [required]

Type: string

Namespace of the enforcer.

enforcerVersion

Type: string

Semantic version of the enforcer.

error

Type: string

A non-empty error indicates a failure.

excludedNetworks

Type: boolean

If true, destination IP is in excludedNetworks.

fourTuple

Type: string

Four tuple in the format sip:dip:spt:dpt.

isServer

Type: boolean

If true, the report was generated by the server.

iterationIndex

Type: integer

Holds the iteration number this probe is attached to.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

payloadSize

Type: integer

Size of the payload attached to the packet.

payloadSizeType [required]

Type: enum(Transmitted | Received)

Type of the payload size.

peerCertExpiry

Type: string

Represents the expiry of the peer certificate.

peerCertIssuer

Type: string

Represents the issuer of the peer certificate.

peerCertSubject

Type: string

Represents the subject of the peer certificate.

pingID [required]

Type: string

PingID unique to a single ping control.

policyAction

Type: string

Action of the policy.

policyID

Type: string

ID of the policy.

policyNamespace

Type: string

ID of the policy.

processingUnitID

Type: string

ID of the reporting processing unit.

protocol

Type: integer

Protocol used for the communication.

remoteController

Type: string

Controller of the remote endpoint.

remoteEndpointType [required]

Type: enum(ProcessingUnit | External)

Represents the remote endpoint type.

remoteNamespace

Type: string

Namespace of the remote processing unit.

remoteNamespaceType [required]

Type: enum(Plain | Hash)

Type of the namespace reported.

remoteProcessingUnitID

Type: string

ID of the remote processing unit.

seqNum

Type: integer

Sequence number of the TCP packet. number.

serviceID

Type: string

ID of the service If the service type is a proxy.

serviceType [autogenerated,read_only]

Type: string

Type of the service.

targetTCPNetworks

Type: boolean

If true, destination IP is in targetTCPNetworks.

type [required]

Type: enum(Request | Response)

Type of the report.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

PingRequest

Initiates a ping request for enforcer debugging.

Example

{
  "iterations": 1,
  "refreshID": "xxxx-xxxx-xxxx"
}

Relations

POST /pingrequests

Initiate a new the ping request.

Attributes

iterations [min_value=1.000000,max_value=20.000000]

Type: integer

Number of probes that will be triggered.

Default value:

1
pingID [autogenerated,read_only]

Type: string

Unique ID generated for each ping request.

refreshID [required]

Type: string

Contains the refresh ID set by processing unit refresh event.

PingResult

Represents the results of a ping request.

Relations

GET /pingresults

Retrieves a ping result.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

errors [autogenerated,read_only]

Type: []string

May contain a list of errors that have happened during the collection.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

pingID [autogenerated,read_only]

Type: string

Contains the Ping ID.

pingPairs

Type: []pingpair

Contains the result of aggregated ping pairs.

refreshID [autogenerated,read_only]

Type: string

Contains the refresh ID set by processing unit refresh event.

remoteProbes

Type: []remotepingprobe

Contains information about missing probes in the result. This field will be populated in the ping probe is managed by a remote controller (federation) or is stored in a namespace you don’t have any permissions on.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

RemotePingProbe

Represents information about a remote ping probe that is governed by a different set of permissions.

Attributes

controllerID [autogenerated,read_only]

Type: string

The controller ID that manages the ping report.

namespace [autogenerated,read_only]

Type: string

The namespace where the ping report is stored. Only applicable when the remote controller is empty.

namespaceType [autogenerated,read_only]

Type: enum(Plain | Hash)

Type of the namespace reported. It can be hash or plain, depending on various factors.

probeID [autogenerated,read_only]

Type: string

The ID of the probe. Only applicable when the remote controller is empty.

TraceMode

Represents the tracing mode to apply to a processing unit.

Example

{
  "IPTables": false,
  "applicationConnections": false,
  "interval": "10s",
  "networkConnections": false
}

Attributes

IPTables

Type: boolean

Instructs the enforcers to provide an iptables trace for a processing unit.

applicationConnections

Type: boolean

Instructs the enforcer to send records for all application-initiated connections.

interval

Type: string

Determines the length of the time interval that the trace must be enabled, using Golang duration syntax.

Default value:

"10s"
networkConnections

Type: boolean

Instructs the enforcer to send records for all network-initiated connections.

TraceRecord

Represents a single trace record from the enforcer.

Example

{
  "TTL": 64,
  "chain": "PREROUTING",
  "destinationIP": "10.1.1.30",
  "destinationInterface": "en0",
  "destinationPort": 80,
  "length": 98,
  "packetID": 10,
  "protocol": 80,
  "ruleID": 10,
  "sourceIP": "10.1.1.30",
  "sourceInterface": "en0",
  "sourcePort": 80,
  "tableName": "raw",
  "timestamp": "2018-06-14T23:10:46.420397985Z"
}

Attributes

TTL [required,max_value=255.000000]

Type: integer

The time to live (TTL) value of the packet.

chain [required]

Type: string

Chain that the trace was collected from.

destinationIP [required]

Type: string

The destination IP.

destinationInterface

Type: string

The destination interface of the packet.

destinationPort [required,min_value=1.000000,max_value=65536.000000]

Type: integer

The destination UPD or TCP port of the packet.

length [required,max_value=65536.000000]

Type: integer

Length of the observed packet.

packetID [required]

Type: integer

The IP packet header ID.

protocol [required,max_value=65536.000000]

Type: integer

The protocol of the packet.

ruleID [required]

Type: integer

Priority index of the iptables entry that was hit.

sourceIP [required]

Type: string

Source IP of the packet.

sourceInterface

Type: string

Source interface of the packet.

sourcePort [required,min_value=1.000000,max_value=65536.000000]

Type: integer

Source TCP or UDP port of the packet.

tableName [required]

Type: string

The iptables name that the trace collected.

timestamp [required]

Type: time

The time-date stamp of the report.

core/monitoring

Activity

Contains logs of all the activity that happened in a namespace. All successful or failed actions will be available, errors, as well as the claims of the user who triggered the actions. This log is capped and only keeps the last 50,000 entries by default.

Relations

GET /activities

Retrieves the list of activity logs.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /activities/:id

Retrieves the object with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

claims [autogenerated,read_only]

Type: object

Claims of the user who performed the operation.

data [autogenerated,read_only]

This attribute is deprecated.

Type: object

This is deprecated in favor of diff.

date [autogenerated,read_only]

Type: time

Time-date stamp of the notification.

diff [autogenerated,read_only]

Type: string

Contains the diff of the change.

error [autogenerated,read_only]

Type: object

Contains the error.

message

Type: string

Message of the notification.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

operation [autogenerated,read_only]

Type: string

Describes what kind of operation the notification represents.

originalData [autogenerated,read_only]

This attribute is deprecated.

Type: object

This is deprecated in favor of diff.

source [autogenerated,read_only]

Type: string

Contains meta information about the source.

targetIdentity [autogenerated,read_only]

Type: string

The identity of the related object.

Alarm

Represents an event requiring attention.

Example

{
  "content": "This is an alarm",
  "emails": [
    "amir@aporeto.com",
    "john@aporeto.com"
  ],
  "kind": "aporeto.alarm.kind",
  "name": "the name",
  "protected": false,
  "status": "Open"
}

Relations

GET /alarms

Retrieves all the alarms.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /alarms

Creates a new alarm.

DELETE /alarms/:id

Deletes the object with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /alarms/:id

Retrieves the object with the given ID.

PUT /alarms/:id

Updates the object with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

content [required,creation_only]

Type: string

Content of the alarm.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

data

Type: []map[string]string

Data represent user data related to the alarms.

description [max_length=1024]

Type: string

Description of the object.

emails

Type: []string

A list of recipients that should be emailed when this alarm is created.

kind [required,creation_only]

Type: string

Identifies the kind of alarm. If two alarms are created with the same identifier, then only the occurrence will be incremented.

lastLocalTimestamp

Type: time

Time and date of the alarm set by the enforcer.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

occurrences [autogenerated,creation_only]

Type: []time.Time

Number of times this alarm has been seen.

protected

Type: boolean

Defines if the object is protected.

status

Type: enum(Acknowledged | Open | Resolved)

Status of the alarm.

Default value:

"Open"
updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

EventLog

Allows you to report various events on any object.

Example

{
  "category": "enforcerd:policy",
  "content": "Unable to activate docker container xyz because abc.",
  "level": "Info",
  "targetID": "xxx-xxx-xxx-xxx",
  "targetIdentity": "processingunit",
  "title": "Error while activating processing unit."
}

Relations

POST /eventlogs

Creates a new event log for a particular entity.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

category [required,creation_only]

Type: string

Category of the event log.

content [required,creation_only]

Type: string

Content of the event log.

date [autogenerated,creation_only]

This attribute is deprecated.

Type: time

Creation date of the event log.

level [creation_only]

Type: enum(Debug | Info | Warning | Error | Critical)

Sets the log level.

Default value:

"Info"
namespace [autogenerated,read_only,creation_only]

Type: string

Namespace tag attached to the event log.

opaque [creation_only]

Type: string

Opaque data that can be attached to the event log, for further machine processing.

targetID [required,creation_only]

Type: string

ID of the object this event log is attached to. The object must be in the same namespace than the event log.

targetIdentity [required,creation_only]

Type: string

Identity of the object this event log is attached to.

timestamp

Type: time

Creation date of the event log.

title [required,creation_only]

Type: string

Title of the event log.

HealthCheck

This API allows to retrieve a generic health state of the platform. A return code different from 200 OK means the platform is not operational. The health check contains the list of observed sub system.

Relations

GET /healthchecks

Retrieve the health of the platform.

Parameters:

  • quiet (boolean): If set to true, the health check endpoint will not return data but will return 200 OK if everything is fine or 218 if the controller is not operational. This is useful when you want to use the health check endpoint as a load balancer health check.

Attributes

alerts [autogenerated,read_only]

Type: []string

A human readable alert list describing the current state of the sub system if available.

name [autogenerated,read_only]

Type: string

The name of the observed sub system if applicable.

responseTime [autogenerated,read_only]

Type: string

The response time of the observed sub system if applicable.

status [autogenerated,read_only]

Type: enum(Degraded | Offline | Operational)

The current health of the observed sub system.

type [autogenerated,read_only]

Type: enum(Cache | Database | General | MessagingSystem | Service | TSDB)

The type of the observed sub system.

Message

Allows you to post public messages that will be visible through all children namespaces.

Example

{
  "level": "Info",
  "name": "the name",
  "propagate": false,
  "protected": false,
  "validity": "12h"
}

Relations

GET /messages

Retrieves the list of messages.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
  • propagated (boolean): Also retrieve the objects that propagate down.
POST /messages

Creates a new message.

DELETE /messages/:id

Deletes the message with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /messages/:id

Retrieves the message with the given ID.

Parameters:

  • propagated (boolean): Also retrieve the objects that propagate down.
PUT /messages/:id

Updates the message with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

description [max_length=1024]

Type: string

Description of the object.

expirationTime [read_only]

Type: time

The time after which the message will be deleted.

level

Type: enum(Danger | Info | Warning)

Importance of the message.

Default value:

"Info"
name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

propagate

Type: boolean

Propagates the policy to all of its children.

protected

Type: boolean

Defines if the object is protected.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

validity [required]

Type: string

Sets when the message will be automatically deleted using Golang duration syntax.

core/namespace

DefaultEnforcerVersion

Returns the default enforcer version of the specified namespace.

Relations

GET /defaultenforcerversion

Returns the default enforcer version of the specified namespace.

POST /defaultenforcerversion

Modify the default enforcer version of the specified namespace.

Attributes

defaultVersion

Type: string

The default enforcer version for the namespace.

LocalCA

Can be used to retrieve or renew the local and SSH certificate authorities of the namespace.

Example

{
  "SSHCertificateRenew": false,
  "certificateRenew": false
}

Relations

GET /localcas

Returns the local and SSH certificate authorities of the namespace.

POST /localcas

Renews the local and/or SSH certificate authorities of the namespace.

Attributes

SSHCertificate [autogenerated,read_only]

Type: string

The SSH certificate authority used by the namespace.

SSHCertificateRenew

Type: boolean

Set to true to renew the SSH certificate authority of the namespace.

certificate [autogenerated,read_only]

Type: string

The certificate authority used by the namespace.

certificateRenew

Type: boolean

Set to true to renew the certificate authority of the namespace.

Namespace

A namespace represents the core organizational unit of the system. All objects always exist in a single namespace. A namespace can also have child namespaces. They can be used to split the system into organizations, business units, applications, services or any combination you like.

Example

{
  "JWTCertificateType": "None",
  "SSHCAEnabled": false,
  "customZoning": false,
  "defaultPUIncomingTrafficAction": "Inherit",
  "defaultPUOutgoingTrafficAction": "Inherit",
  "localCAEnabled": false,
  "name": "mynamespace",
  "protected": false,
  "serviceCertificateValidity": "168h",
  "type": "Default"
}

Relations

GET /namespaces

Retrieves the list of namespaces.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /namespaces

Creates a new namespace.

DELETE /namespaces/:id

Deletes the namespace with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /namespaces/:id

Retrieves the namespace with the given ID.

PUT /namespaces/:id

Updates the namespace with the given ID.

GET /namespaces/:id/oauthinfo

Retrieves the OAUTH info for this namespace.

Parameters:

  • mode (enum(oidc)): When set to type OIDC it will return the data as a raw JSON object and not a Microsegmentation Console-compatible API.
GET /namespaces/:id/oauthkeys

Retrieves the OAUTH info for this namespace.

Parameters:

  • mode (enum(oidc)): When set to OIDC it will return the data as a raw JSON object and not a Microsegmentation Console-compatible API.
GET /namespaces/:id/trustedcas

Returns the list of trusted CAs for this namespace.

Parameters:

  • type (enum(Any | X509 | SSH | JWT)): Type of certificate to get.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

JWTCertificateType

Type: enum(RSA | EC | None)

JWTCertificateType defines the JWT signing certificate that must be created for this namespace. If the type is none no certificate will be created.

Default value:

"None"
JWTCertificates [autogenerated,read_only]

Type: map[string]string

JWTCertificates hold the certificates used to sign tokens for this namespace. This is map indexed by the ID of the certificate.

SSHCAEnabled

This attribute is deprecated.

Type: boolean

If true, an SSH certificate authority (CA) will be generated for the namespace. This CA can be deployed in SSH server to validate SSH certificates issued by the controller.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedSSHCAID [read_only]

Type: string

The remote ID of the SSH certificate authority to use.

associatedTags

Type: []string

List of tags attached to an entity.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

customZoning [creation_only]

Type: boolean

Defines if the namespace should inherit its parent zone. If this property is set to false, the zoning property will be ignored and the namespace will have the same zone as its parent.

defaultEnforcerVersion

Type: string

Indicates the default enforcer version for this namespace.

defaultPUIncomingTrafficAction

Type: enum(Allow | Reject | Inherit)

Describes the default action a processing unit will take for incoming traffic for this namespace.

Default value:

"Inherit"
defaultPUOutgoingTrafficAction

Type: enum(Allow | Reject | Inherit)

Describes the default action a processing unit will take for outgoing traffic for this namespace.

Default value:

"Inherit"
description [max_length=1024]

Type: string

Description of the object.

localCAEnabled

Type: boolean

Defines if the namespace should use a local certificate authority (CA). Switching it off and on again will regenerate a new CA.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

name [required,creation_only,format=^[a-zA-Z0-9-_/]+$]

Type: string

The name of the namespace.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

networkAccessPolicyTags

This attribute is deprecated.

Type: []string

List of tags that will be added to every or clause of all network access policies in the namespace and its children.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

organizationalMetadata

Type: []string

List of tags that describe this namespace. All organizational tags are automatically passed to policeable objects (e.g., processing units, external networks, enforcers) during their creation.

protected

Type: boolean

Defines if the object is protected.

serviceCertificateValidity

This attribute is deprecated.

Type: string

This flag is deprecated and has no incidence.

Default value:

"168h"
tagPrefixes

Type: []string

List of tag prefixes that will be used to suggest policies. Only these tags will be transmitted on the wire.

type [creation_only]

Type: enum(Default | Tenant | CloudAccount | Group | Kubernetes)

The type defines the purpose of the namespace: - Default: A universal namespace that is capable of all actions and views. - Tenant: A namespace that houses a tenant (e.g. ACME). - CloudAccount: A child namespace of a tenant that houses a cloud provider account. - Group: A child namespace of a cloud account that houses a managed group. - Kubernetes: A child namespace of a group that houses a Kubernetes cluster (automatically created by the enforcer).

Default value:

"Default"
updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

zoning [creation_only]

Type: integer

Defines what zone the namespace should live in.

NamespaceMappingPolicy

A namespace mapping defines the namespace a processing unit should be placed when it is created, based on its tags. When an enforcer creates a new processing unit, the system will place it in its own namespace if no matching namespace mapping can be found. If one match is found, then the processing unit will be bumped down to the namespace declared in the namespace mapping. If it finds in that child namespace another matching namespace mapping, then the processing unit will be bumped down again, until it reaches a namespace with no matching namespace mappings. This is very useful to dispatch processes and containers into a particular namespace, based on a lot of factors. For example, you can put in place a quarantine namespace mapping that will grab all processing units with excessive vulnerabilities.

Example

{
  "disabled": false,
  "mappedNamespace": "/blue/namespace",
  "name": "the name",
  "protected": false,
  "subject": [
    [
      "color=blue"
    ]
  ]
}

Relations

GET /namespacemappingpolicies

Retrieves the list namespace mappings.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
POST /namespacemappingpolicies

Creates a new namespace mapping.

DELETE /namespacemappingpolicies/:id

Deletes the mapping with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /namespacemappingpolicies/:id

Retrieves the mapping with the given ID.

PUT /namespacemappingpolicies/:id

Updates the mapping with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

description [max_length=1024]

Type: string

Description of the object.

disabled

Type: boolean

Defines if the property is disabled.

mappedNamespace [required,format=^[a-zA-Z0-9-_/]+$]

Type: string

The namespace to map the subject to.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

protected

Type: boolean

Defines if the object is protected.

subject

Type: [][]string

A tag or tag expression identifying the entity to be mapped.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

NamespacePolicyInfo

Returns the policy info of the specified namespace.

Example

{
  "PUIncomingTrafficAction": "Allow",
  "PUOutgoingTrafficAction": "Allow"
}

Relations

GET /namespacepolicyinfo

Returns the policy info of the specified namespace.

Attributes

PUIncomingTrafficAction [read_only]

Type: enum(Allow | Reject | Inherit)

The processing unit action for incoming traffic for the namespace.

PUOutgoingTrafficAction [read_only]

Type: enum(Allow | Reject | Inherit)

The processing unit action for outgoing traffic for the namespace.

prefixes [read_only]

Type: []string

List of tag prefixes that will be used to suggest policies.

NamespaceRenderer

This object allows you to determine which namespace an object should reside in based on the tags provided.

Example

{
  "tags": [
    "a=a",
    "b=b"
  ]
}

Relations

POST /namespacerenderers

Renders the namespace where an object should reside.

Attributes

namespace [autogenerated,read_only]

Type: string

The namespace where the object should reside in.

tags [required]

Type: []string

List of tags of the object to render the namespace for.

NamespaceType

Returns the type of the specified namespace.

Relations

GET /namespacetypes

Returns the type of the specified namespace.

Attributes

type [autogenerated,read_only]

Type: string

the namespace type for the current namespace.

OrganizationalMetadata

Can be used to retrieve the organizational metadata of the namespace.

Relations

GET /organizationalmetadata

Retrieves the list of organizational metadata for the namespace and its namespace hierarchy.

Attributes

metadata

Type: []string

List of organizational metadata for the namespace.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

TagPrefix

Returns the tag prefixes of the specified namespace.

Relations

GET /tagprefixes

Returns the tag prefixes of the specified namespace.

POST /tagprefixes

Modify the tag prefixes of the specified namespace.

Attributes

prefixes

Type: []string

List of tag prefixes that will be used to suggest policies. Only these tags will be transmitted on the wire.

core/policy

ClauseMatch

This API allows to pass a set of tags and find the objects that would match the clause in a policy resolution.

Example

{
  "clauses": [
    [
      "color=blue",
      "size=big"
    ],
    [
      "color=red"
    ]
  ],
  "targetIdentity": "processingunit"
}

Relations

POST /clausesmatches

Performs a clause matching.

Attributes

clauses [required]

Type: [][]string

The tag clause to resolve.

match [autogenerated,read_only]

Type: []map[string]interface{}

Contains the matched objects.

targetIdentity [required]

Type: string

The identity to render the clauses from.

EnforcerRefresh

Sent to enforcers when a poke has been triggered using the parameter ?notify=true. This is used to notify an enforcer of an external change on the processing unit that must be processed.

Example

{
  "debug": "Counters",
  "propagate": false,
  "refreshType": "Debug",
  "selector": [
    [
      "$namespace=/a/b"
    ]
  ]
}

Relations

POST /enforcerrefreshes

Create an enforcer refresh report.

POST /enforcers/:id/enforcerrefreshes

Sends a enforcer refresh command.

Attributes

ID [identifier,read_only]

Type: string

Contains the ID of the target enforcer.

debug

Type: enum(Counters | Logs | Packets | PUState | Pcap | CoreDump)

Set the debug information collected by the enforcer.

Default value:

"Counters"
debugID

Type: string

Can be used to correlate with a DebugBundle.

debugPcapFilter

Type: string

Packet capture filter, syntax varying by platform.

debugProcessingUnitID

Type: string

Isolates debug information to a given processing unit, where possible.

migrationVersion

Type: string

Defines the version to migrate enforcers.

namespace [autogenerated,read_only]

Type: string

Contains the original namespace of the enforcer.

propagate

Type: boolean

Propagates the policy to all of its children.

refreshType

Type: enum(Debug | Migration)

Indicates the type of refresh.

Default value:

"Debug"
selector

Type: [][]string

Request a command for the enforcers matching the following tag expression.

NetworkRule

Represents an ingress or egress network rule.

Example

{
  "action": "Allow",
  "logsDisabled": false,
  "observationEnabled": false
}

Attributes

action [required]

Type: enum(Allow | Reject)

Defines the action to apply to a flow. - Allow: allows the defined traffic. - Reject: rejects the defined traffic; useful in conjunction with an allow all policy.

Default value:

"Allow"
logsDisabled

Type: boolean

If true, the relevant flows will not be reported to the Microsegmentation Console. Under some advanced scenarios you may wish to set this to true, such as to save space or improve performance.

name [max_length=16]

Type: string

A user defined name to keep track of the rule in the reporting.

networks [read_only]

Type: []networkrulenet

A list of IP CIDRS or FQDNS that identify remote endpoints.

object

Type: [][]string

Identifies the set of remote workloads that the rule relates to. The selector will identify both processing units as well as external networks that match the selector.

observationEnabled

Type: boolean

If set to true, the flow will be in observation mode.

Default value:

false
protocolPorts

Type: []string

Represents the ports and protocols this policy applies to. Protocol/ports are defined as tcp/80, udp/22. For protocols that do not have ports, the port designation is not allowed.

NetworkRuleNet

Represents an network contained in a NetworkRule.

Attributes

ID [read_only]

Type: string

The ID of the external network.

entries [read_only]

Type: []string

List of CIDRs or domain name.

namespace [read_only]

Type: string

The namespace of the external network.

Policy

Represents the policy primitive used by all Microsegmentation policies.

Example

{
  "disabled": false,
  "fallback": false,
  "name": "the name",
  "propagate": false,
  "propagationHidden": false,
  "protected": false,
  "type": "APIAuthorization"
}

Relations

GET /policies

Retrieves the list of policy primitives.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
  • propagated (boolean): Also retrieve the objects that propagate down.
DELETE /policies/:id

Deletes the object with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /policies/:id

Retrieves the object with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

action

Type: map[string]map[string]interface{}

Defines a set of actions that must be enforced when a dependency is met.

activeDuration [format=^[0-9]+[smh]$]

Type: string

Defines for how long the policy will be active according to the activeSchedule.

activeSchedule

Type: string

Defines when the policy should be active using the cron notation. The policy will be active for the given activeDuration.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

description [max_length=1024]

Type: string

Description of the object.

disabled

Type: boolean

Defines if the property is disabled.

expirationTime

Type: time

If set the policy will be automatically deleted at the given time.

fallback

Type: boolean

Indicates that this is fallback policy. It will only be applied if no other policies have been resolved. If the policy is also propagated it will become a fallback for children namespaces.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

object

Type: [][]string

Represents set of entities that another entity depends on. As subjects, objects are identified as logical operations on tags when a policy is defined.

propagate

Type: boolean

Propagates the policy to all of its children.

propagationHidden

Type: boolean

If set to true while the policy is propagating, it won’t be visible to children namespace, but still used for policy resolution.

protected

Type: boolean

Defines if the object is protected.

relation

Type: []string

Describes the required operation to be performed between subjects and objects.

subject

Type: [][]string

Represents sets of entities that will have a dependency other entities. Subjects are defined as logical operations on tags. Logical operations can include AND and OR.

type [creation_only]

Type: enum(APIAuthorization | AuditProfileMapping | EnforcerProfile | File | Hook | HostServiceMapping | Infrastructure | NamespaceMapping | Network | NetworkRuleSet | ProcessingUnit | Quota | Service | ServiceDependency | Syscall | TokenScope | SSHAuthorization | UserAccess)

Type of the policy.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

PolicyRefresh

Sent to a client as a push event when a policy refresh is needed on their side.

Attributes

sourceID

Type: string

Contains the original ID of the updated object.

sourceNamespace

Type: string

Contains the original namespace of the updated object.

type

Type: string

Contains the policy type that is affected.

PolicyRule

Allows services to retrieve a policy resolution (internal).

Example

{
  "name": "the name",
  "propagated": false
}

Relations

GET /policyrules/:id

Retrieves the object with the given ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

action

Type: map[string]map[string]interface{}

Defines set of actions that must be enforced when a dependency is met.

auditProfiles

This attribute is deprecated.

Type: []auditprofile

Provides the audit profiles that must be applied.

enforcerProfiles

Type: []enforcerprofile

Provides information about the enforcer profile.

externalNetworks

Type: []externalnetwork

Provides the external network that the policy targets.

filePaths

This attribute is deprecated.

Type: []filepath

Provides the file paths that the policy targets.

hostServices

Type: []hostservice

Provides the list of host services that must be instantiated.

isolationProfiles

This attribute is deprecated.

Type: []isolationprofile

Provides the isolation profiles of the rule.

name [required,max_length=256]

Type: string

Name of the entity.

namespaces

Type: []namespace

The namespace that the policy targets.

policyNamespace

Type: string

The namespace of the policy that created this rule.

policyUpdateTime

Type: time

Last time the policy was updated.

propagated

Type: boolean

Indicates if the policy is propagated.

relation

Type: []string

Describes the required operation to be performed between subjects and objects.

services

Type: []service

Provides the services of this policy rule.

tagClauses

Type: [][]string

Policy target tags.

ProcessingUnitRefresh

Sent to client when a poke has been triggered using the parameter ?notify=true. This is used to notify a enforcer of an external change on the processing unit must be processed.

Example

{
  "debug": false,
  "pingEnabled": false,
  "pingIterations": 1,
  "pingMode": "Auto",
  "refreshPolicy": false,
  "traceApplicationConnections": false,
  "traceDuration": "10s",
  "traceIPTables": false,
  "traceNetworkConnections": false
}

Relations

POST /processingunits/:id/processingunitrefreshes

Sends a Processing Unit Refresh command.

Attributes

ID [identifier,read_only]

Type: string

Contains the ID of the target processing unit.

debug

Type: boolean

If set to true, start reporting debug information for the target processing unit.

namespace [autogenerated,read_only]

Type: string

Contains the original namespace of the processing unit.

pingAddress

Type: string

Destination address to run ping.

pingEnabled

Type: boolean

If set to true, start ping to the destination.

pingIterations [min_value=1.000000]

Type: integer

Number of iterations to run a ping probe.

Default value:

1
pingMode

Type: enum(Auto | L3 | L4 | L7)

Represents the mode of ping to be used.

Default value:

"Auto"
pingPort

Type: integer

Destination port to run ping.

refreshID [read_only]

Type: string

ID unique per ProcessingUnitRefresh event.

refreshPolicy

Type: boolean

If set to true, the target processing unit will refresh its policy immediately.

traceApplicationConnections

Type: boolean

Instructs the enforcer to send records for all application-initiated connections for the target processing unit.

traceDuration

Type: string

Determines the length of the time interval that the trace must be enabled, using Golang duration syntax.

Default value:

"10s"
traceIPTables

Type: boolean

Instructs the enforcers to provide an iptables trace for the target processing unit.

traceNetworkConnections

Type: boolean

Instructs the enforcer to send records for all network-initiated connections for the target processing unit.

RenderedPolicy

Retrieve the aggregated policies applied to a particular processing unit.

Example

{
  "defaultPUIncomingTrafficAction": "Reject",
  "defaultPUOutgoingTrafficAction": "Reject",
  "processingUnit": "{
  \"name\": \"pu\",
  \"type\": \"Docker\",
  \"normalizedTags\": [
    \"a=a\",
    \"b=b\"
  ]
}"
}

Relations

POST /renderedpolicies

Render a policy for a processing unit.

Parameters:

  • renderer (enum(v1 | v2)): Select the network policy renderer to use.
GET /processingunits/:id/renderedpolicies

Retrieves the policies for the processing unit.

Parameters:

  • renderer (enum(v1 | v2)): Select the network policy renderer to use.

Attributes

certificate [read_only]

This attribute is deprecated.

Type: string

The certificate associated with this processing unit. It will identify the processing unit to any internal or external services.

datapathType [autogenerated,read_only]

This attribute is deprecated.

Type: enum(Default | Aporeto | EnvoyAuthorizer)

The datapath type that this processing unit must implement according to the rendered policy: - Default: This policy is not making a decision for the datapath. - Aporeto: The enforcer is managing and handling the datapath. - EnvoyAuthorizer: The enforcer is serving Envoy-compatible gRPC APIs that for example can be used by an Envoy proxy to use the Microsegmentation PKI and implement Microsegmentation network policies. NOTE: The enforcer is not owning the datapath in this case. It is merely providing an authorizer API.

defaultPUIncomingTrafficAction

Type: enum(Allow | Reject)

Describes the default for incoming traffic.

Default value:

"Reject"
defaultPUOutgoingTrafficAction

Type: enum(Allow | Reject)

Describes the default for outgoing traffic.

Default value:

"Reject"
dependendServices

Type: []service

The list of services that this processing unit depends on.

egressPolicies [autogenerated,read_only]

This attribute is deprecated.

Type: _rendered_policy

Lists all the egress policies attached to processing unit.

exposedServices

Type: []service

The list of services that this processing unit is implementing.

hashedTags [autogenerated,read_only]

Type: map[string]string

Contains the list of all tags and their hashed that have been used.

ingressPolicies [autogenerated,read_only]

This attribute is deprecated.

Type: _rendered_policy

Lists all the ingress policies attached to the processing unit.

matchingTags [autogenerated,read_only]

This attribute is deprecated.

Type: []string

Contains the list of tags that matched the policies.

processingUnit [creation_only]

This attribute is deprecated.

Type: processingunit

Can be set during a POST operation to render a policy on a processing unit that has not been created yet.

processingUnitID [autogenerated,read_only]

This attribute is deprecated.

Type: string

Identifier of the processing unit.

processingUnitTags [creation_only]

Type: []string

Can be set during a POST operation to render a policy on a processing unit tags.

rendererVersion [autogenerated,read_only]

Type: integer

Indicates the version of the engine used to render the policies.

ruleSetPolicies [autogenerated,read_only]

Type: []policyrule

Lists all the rule set policies attached to processing unit.

scopes

Type: []string

The set of scopes granted to this processing unit that has to be present in HTTP requests.

wireTags [autogenerated,read_only]

Type: []string

Contains the list of tags that must go on the wire.

core/processingunit

DataPathCertificate

Used by enforcer instances to retrieve various certificates used for the datapath.

Example

{
  "CSR": "-----BEGIN CERTIFICATE REQUEST-----
MIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV
BAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln
aUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo
wp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c
1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI
WDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ
wIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR
BPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ
KoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D
hJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY
Q4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/
ZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn
29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2
97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=
-----END CERTIFICATE REQUEST-----",
  "objectID": "5c83035648675400019ab901",
  "sessionID": "5c83035648675400019ab901",
  "type": "Service"
}

Relations

POST /datapathcertificates

Creates a new certificate for datapath.

Attributes

CSR [required]

Type: string

Contains a certificate signing request (CSR) from the enforcer. Depending on the certificate there will be various requirements for the Microsegmentation Console to accept the CSR.

certificate [autogenerated,read_only]

Type: string

The certificate.

objectID [required]

Type: string

ID of the object you want to issue a certificate for.

sessionID

Type: string

Provides the session ID of the enforcer when retrieving a datapath certificate.

signer [autogenerated,read_only]

Type: string

Contains the CA that signed the delivered certificate.

token [autogenerated,read_only]

Type: string

Contains a cryptographic token.

type

Type: enum(Enforcer | Service | ServicePing)

Type of certificate.

ProcessingUnit

A processing unit represents anything that can compute. It can be a Docker container or a simple UNIX process. Processing units are created, updated, and deleted by the system as they come and go. You can only modify their tags. Processing units use network policies to define which other processing units or external networks they can communicate with and file access policies to define what file paths they can use.

Example

{
  "collectInfo": false,
  "datapathType": "Aporeto",
  "enforcementStatus": "Inactive",
  "name": "the name",
  "operationalStatus": "Initialized",
  "protected": false,
  "type": "Docker"
}

Relations

GET /processingunits

Retrieves the list of processing units.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
  • archived (boolean): Also retrieve the objects that have been archived.
POST /processingunits

Creates a new processing unit.

DELETE /processingunits/:id

Deletes the processing unit with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /processingunits/:id

Retrieves the processing unit with the given ID.

Parameters:

  • archived (boolean): Also retrieve the objects that have been archived.
PUT /processingunits/:id

Updates the processing unit with the given ID.

GET /fileaccesspolicies/:id/processingunits

Returns the list of processing units that match the policy.

GET /infrastructurepolicies/:id/processingunits

Returns the list of processing units affected by an infrastructure policy.

Parameters:

  • mode (enum(subject | object)): Matching mode.
GET /networkaccesspolicies/:id/processingunits

Returns the list of processing units affected by a network policy.

Parameters:

  • mode (enum(subject | object)): Matching mode.
GET /networkrulesetpolicies/:id/processingunits

Returns the list of processing units affected by a network rule set policy.

Parameters:

  • mode (enum(subject | object)): Matching mode.
GET /processingunitpolicies/:id/processingunits

Returns the list of processing units referenced by the mapping.

GET /servicedependencies/:id/processingunits

Returns the list of processing units that depend on an service.

GET /services/:id/processingunits

Retrieves the processing units that implement this service.

GET /vulnerabilities/:id/processingunits

Retrieves the processing units affected by the vulnerability.

POST /processingunits/:id/pingprobes

Create a ping probe.

GET /processingunits/:id/poke

Sends a poke empty object. This will send a snapshot of the processing unit to the time series database.

Parameters:

  • enforcementStatus (enum(Failed | Inactive | Active)): If set, changes the enforcement status of the processing unit alongside with the poke.
  • forceFullPoke (boolean): If set, it will trigger a full poke (slower).
  • notify (boolean): Can be sent to trigger a ProcessingUnitRefresh event that will be handled by the enforcer. If this is set, all other additional parameters will be ignored.
  • status (enum(Initialized | Paused | Running | Stopped)): If set, changes the status of the processing unit alongside with the poke.
  • ts (time): time of report. If not set, local server time will be used.
  • zhash (integer): Can be set to help backend target the correct shard where the processing unit is stored.
POST /processingunits/:id/processingunitrefreshes

Sends a Processing Unit Refresh command.

GET /processingunits/:id/renderedpolicies

Retrieves the policies for the processing unit.

Parameters:

  • renderer (enum(v1 | v2)): Select the network policy renderer to use.
GET /processingunits/:id/services

Retrieves the services used by a processing unit.

GET /processingunits/:id/vulnerabilities

Retrieves the vulnerabilities affecting the processing unit.

Parameters:

  • propagated (boolean): Also retrieve the objects that propagate down.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

clientLocalID

Type: string

The local PUID set by enforcer. Enforcer may create a local PU if it cannot communicate with the Microsegmentation Console. When eventually the Microsegmentation Console is able to create the PU, the clientLocalID will be used to convert a CachedFlowReport containing a local PUID to a real FlowReport.

collectInfo

Type: boolean

A value of true indicates to the enforcer that it needs to collect information for this processing unit.

collectedInfo

Type: map[string]string

Represents the latest information collected by the enforcer for this processing unit.

controller [autogenerated,read_only]

Type: string

The Microsegmentation Console identifier managing this object. This property is mostly useful when federating multiple Microsegmentation Consoles.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

datapathType

Type: enum(Aporeto | EnvoyAuthorizer)

The datapath type that processing units are implementing: - Aporeto: The enforcer is managing and handling the datapath. - EnvoyAuthorizer: The enforcer is serving Envoy-compatible gRPC APIs that for example can be used by an Envoy proxy to use the Microsegmentation PKI and implement Microsegmentation network policies. NOTE: The enforcer is not owning the datapath in this case. It is merely providing an authorizer API.

Default value:

"Aporeto"
description [max_length=1024]

Type: string

Description of the object.

enforcementStatus

Type: enum(Active | Failed | Inactive)

Contains the state of the enforcer for the processing unit.

Inactive (default): the enforcer is not enforcing any host service. Active: the enforcer is enforcing a host service. Failed: an error occurred during the enforcement attempt.

Default value:

"Inactive"
enforcerID

Type: string

The ID of the enforcer associated with the processing unit.

enforcerNamespace

Type: string

The namespace of the enforcer associated with the processing unit.

image

This attribute is deprecated.

Type: string

This field is deprecated and it is there for backward compatibility. Use images instead.

images [creation_only]

Type: []string

List of images or executable paths used by the processing unit.

lastCollectionTime

Type: time

The date and time when the information was collected.

lastLocalTimestamp

Type: time

Time and date of the processing unit set by the enforcer.

lastSyncTime [autogenerated]

Type: time

The date and time of the last policy resolution.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

nativeContextID

Type: string

The Docker UUID or service PID.

networkServices

Type: []processingunitservice

The list of services that this processing unit has declared that it will be listening to, either in its activation command or by exposing the ports in a container manifest.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

operationalStatus

Type: enum(Initialized | Paused | Running | Stopped | Terminated)

Operational status of the processing unit: Initialized (default), Paused, Running, Stopped, or Terminated.

Default value:

"Initialized"
protected

Type: boolean

Defines if the object is protected.

tracing

Type: tracemode

Indicates if this processing unit must be placed in tracing mode.

type [creation_only]

Type: enum(APIGateway | Docker | Host | HostService | LinuxService | WindowsService | RKT | User | SSHSession)

Type of processing unit: APIGateway, Docker, Host, HostService, LinuxService, WindowsService, RKT, User, or SSHSession.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

vulnerabilityLevel [autogenerated,read_only]

This attribute is deprecated.

Type: string

List of vulnerabilities affecting this processing unit.

Vulnerability

Represents a common vulnerability and exposure (CVE).

Example

{
  "CVSS2Score": 3.2,
  "link": "https://cve.com/CVE-1234",
  "name": "the name",
  "propagate": false,
  "protected": false,
  "severity": 3
}

Relations

GET /vulnerabilities

Retrieves the list of vulnerabilities.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
  • propagated (boolean): Also retrieve the objects that propagate down.
POST /vulnerabilities

Creates a new vulnerability.

GET /vulnerabilities/:id

Retrieves the object with the given ID.

GET /processingunits/:id/vulnerabilities

Retrieves the vulnerabilities affecting the processing unit.

Parameters:

  • propagated (boolean): Also retrieve the objects that propagate down.
GET /vulnerabilities/:id/processingunits

Retrieves the processing units affected by the vulnerability.

Attributes

CVSS2Score [creation_only]

Type: float

Common Vulnerability Scoring System (CVSS) version 2 score.

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

description [max_length=1024]

Type: string

Description of the object.

Type: string

The URL that refers to the vulnerability.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

propagate

Type: boolean

Propagates the policy to all of its children.

protected

Type: boolean

Defines if the object is protected.

severity [required,creation_only]

Type: _vulnerability_level

Refers to the security vulnerability level.

core/rql

CNSSearch

Provide search results for Prisma Cloud’s investigate page.

Example

{
  "endAbsolute": 0,
  "limit": 100,
  "query": "network dns where id == 1",
  "saved": false,
  "startAbsolute": 0
}

Relations

POST /cnssearches

Retrieves RQL search results.

Attributes

ID

Type: string

ID of the search request.

data

Type: pcsearchresult

The payload of the search results.

description

Type: string

Description of the search.

endAbsolute

Type: integer

Absolute end time of search, in UNIX time.

Default value:

0
limit

Type: integer

The number of items to fetch.

Default value:

100
name

Type: string

Name of the RQL search request. Should set to be empty.

pageToken

Type: string

Represents the token to fetch next page.

query [required]

Type: string

The RQL query.

saved

Type: boolean

Indicates if the search has been saved.

searchType

Type: string

Type of search request. Should set to be network.

startAbsolute

Type: integer

Absolute start time of search, in UNIX time.

Default value:

0
timeRange

Type: pctimerange

Time range used by PC APIs. Its type is dynamic. Aporeto needs to pass this data to PC backend.

CNSSuggestion

Provides query suggestions for Prisma Cloud’s investigate page.

Example

{
  "needsOffsetUpdate": true,
  "offset": 0,
  "query": "network from DNS where id == 1",
  "suggestions": [
    "id",
    "action"
  ],
  "translate": false,
  "valid": false
}

Relations

POST /cnssuggestions

Retrieves RQL suggestions from Microsegmentation.

Attributes

needsOffsetUpdate

Type: boolean

Required by Prisma Cloud. Always set to true.

Default value:

true
offset

Type: integer

The length of the RQL query part that is valid.

Default value:

0
query [read_only]

Type: string

Prisma Cloud’s RQL query.

suggestions

Type: []string

List of query suggestions.

translate

Type: boolean

Required by Prisma Cloud. Always set to false.

Default value:

false
valid

Type: boolean

The validity of the RQL query.

Default value:

false

PCSearchResult

Represents the result data of RQL search.

Attributes

internalEdges [autogenerated,read_only]

Type: map[string]cloudgraphedge

The edges of the map connecting internal endpoints.

items [read_only]

Type: reportsquery

The payload of the search result.

nextPageToken [read_only]

Type: string

The pagination token for next page.

nodes [autogenerated,read_only]

Type: map[string]cloudgraphnode

Refers to the nodes of the map.

publicEdges [autogenerated,read_only]

Type: map[string]cloudgraphedge

The edges of the map connecting public endpoints.

sourceDestinationMap [autogenerated,read_only]

Type: map[string]map[string]cloudnetworkquerydestination

The set of destinations that have been discovered based on the query and their associated verdicts.

totalRows [read_only]

Type: integer

The total number of result items.

PCTimeRange

Represents the time range parameter of PC.

Attributes

relativeTimeType [read_only]

Type: string

The type of relative time.

type [read_only]

Type: string

The type of time range.

value [read_only]

Type: pctimevalue

The value of time range.

core/tag

Tag

A tag is a key-value pair in string form that can applied to all objects in the system. They are used for policy resolution. Tags starting with $ are derived from the property of an object. For example an object with an ID set to xxx and a name set to the name will be tagged by default with $name=the name and $id=xxx. Tags starting with an @ have been generated by an external system.

Example

{
  "value": "key=value"
}

Relations

GET /tags

Retrieves the list of existing tags in the system.

Parameters:

  • onlyPolicyTags (boolean): if set to true, only return tags that match the tag prefixes.
  • q (string): Filtering query. Consequent q parameters will form an or.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

count [autogenerated,read_only]

Type: integer

Represents the number of times the tag is used.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

value [required,creation_only]

Type: string

Represents the value of the tag.

TagValue

Represents all values associated to a tag key.

Relations

GET /tagvalues

Retrieves the list of existing values for the given tag keys.

Parameters:

  • key (string): Keys of the tag you want to get the values of.

Mandatory Parameters

key

Attributes

key [autogenerated,read_only]

Type: string

The requested key.

values [autogenerated,read_only]

Type: []string

List of all values.

core/tenant

Tenant

Can be used to create a tenant’s namespace and API authorization policy to grant access.

Example

{
  "externalID": "customer-123",
  "name": "acme"
}

Relations

POST /tenants

Creates the tenant’s namespace and API authorization policy.

DELETE /tenants/:id

Delete the tenant with the given Prisma or namespace ID.

GET /tenants/:id

Retrieve the tenant with the given Prisma or namespace ID.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

externalID [required]

Type: string

The external ID of the tenant.

name [required,format=^[a-zA-Z0-9-_/]+$,max_length=231]

Type: string

The name of the tenant.

core/workflow

Recipe

Defines a list of steps that make up a workflow.

Example

{
  "deploymentMode": "Unrestricted",
  "label": "magicpanda",
  "name": "the name",
  "propagate": false,
  "protected": false,
  "targetIdentities": [
    "processingunit",
    "enforcer"
  ]
}

Relations

GET /recipes

Retrieves the list of recipes.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
  • propagated (boolean): Also retrieve the objects that propagate down.
POST /recipes

Creates a new recipe.

DELETE /recipes/:id

Deletes the recipe with the given ID.

Parameters:

  • q (string): Filtering query. Consequent q parameters will form an or.
GET /recipes/:id

Retrieves the recipe with the given ID.

Parameters:

  • propagated (boolean): Also retrieve the objects that propagate down.
PUT /recipes/:id

Updates the recipe with the given ID.

GET /recipes/:id/importreferences

Returns the list of import references that depend on a recipe.

POST /recipes/:id/importreferences

Create an import request for the given recipe.

Attributes

ID [identifier,autogenerated,read_only]

Type: string

Identifier of the object.

annotations

Type: map[string][]string

Stores additional information about an entity.

associatedTags

Type: []string

List of tags attached to an entity.

createTime [autogenerated,read_only]

Type: time

Creation date of the object.

deploymentMode

Type: enum(Unrestricted | Unique | NamespaceUnique)

Defines the deployment mode of the recipe. If Unrestricted, the recipe can be deployed multiple times in the current namespace and below. If Unique, only one deployment is allowed in the current namespace and its child namespaces. If NamespaceUnique, only one deployment is allowed in the current namespace.

Default value:

"Unrestricted"
description [max_length=1024]

Type: string

Description of the object.

icon

Type: string

Contains a base64-encoded image for the recipe.

key [read_only]

Type: string

The unique key of the recipe.

label [required,creation_only]

Type: string

Defines the recipe.

Default value:

"magicpanda"
longDescription

Type: string

Provides a long description of the recipe.

metadata [creation_only]

Type: []string

Contains tags that can only be set during creation, must all start with the ‘@’ prefix, and should only be used by external systems.

name [required,max_length=256]

Type: string

Name of the entity.

namespace [autogenerated,read_only]

Type: string

Namespace tag attached to an entity.

normalizedTags [autogenerated,read_only]

Type: []string

Contains the list of normalized tags of the entities.

options

Type: recipeoptions

Options of the recipe.

propagate

Type: boolean

Propagates the policy to all of its children.

protected

Type: boolean

Defines if the object is protected.

steps

Type: []uistep

Contains all the steps with parameters to follow for the recipe.

successfullMessage

Type: string

A string message presented upon success (optional).

targetIdentities [required]

Type: []string

Contains the list of identities the recipes will try to create.

template

Type: string

Template of the recipe to import.

templateHash [read_only]

Type: string

A hash of the template.

updateTime [autogenerated,read_only]

Type: time

Last update date of the object.

RecipeOptions

Represents recipe options.

Example

{
  "appCrendentialFormat": "JSON"
}

Attributes

appCrendentialFormat

Type: enum(JSON | YAML)

Indicates the format of the app credential.

Default value:

"JSON"

RenderTemplate

Cooks a template based on some parameters.

Relations

POST /rendertemplates

Renders a new template.

Attributes

output

Type: string

Holds the rendered template.

parameters

Type: map[string]interface{}

Contains the computed parameters.

template

Type: string

Template of the recipe.

UIParameter

Represents a parameter that will be shown in the web interface.

Example

{
  "advanced": false,
  "key": "unique_key",
  "optional": false,
  "type": "String",
  "width": "100%"
}

Attributes

advanced

Type: boolean

A value of true designates the parameter as advanced.

allowedChoices

Type: map[string]string

Lists all the choices in case of an enum.

allowedValues

Type: []object

List of values that can be used.

defaultValue

Type: object

Default value of the parameter.

description

Type: string

Description of the parameter.

key [required]

Type: string

Key identifying the parameter.

longDescription

Type: string

Long explanation of the parameter.

name

Type: string

Name of the parameter.

optional

Type: boolean

A value of true designates the parameter as optional.

subtype

Type: string

The subtype of a list parameter.

type [required]

Type: enum(Boolean | Checkbox | CVSSThreshold | DangerMessage | Duration | Enum | Endpoint | FileDrop | Float | FloatSlice | InfoMessage | Integer | IntegerSlice | JSON | List | Message | Namespace | Password | String | StringSlice | Switch | TagsExpression | Title | WarningMessage)

The datatype of the parameter.

validationFunction

Type: string

A function that validates the parameter.

value

This attribute is deprecated.

Type: object

Value of the parameter.

visibilityCondition

Type: uiparametersexpression

A logical expression consisting of one or more UIParameterVisibility conditions linked together using AND or OR operators. If the expression evaluates to true the parameter is displayed to the user.

width

Type: string

Width of the parameter.

Default value:

"100%"

UIParameterVisibility

Represents a visibility condition for a UIParameter.

Example

{
  "key": "enableThing",
  "operator": "Equal",
  "value": true
}

Attributes

key [required]

Type: string

Key holding the value to compare.

operator

Type: enum(Equal | NotEqual | GreaterThan | LesserThan | Defined | Undefined | Match | NotMatch)

Operator to apply.

value [required]

Type: object

Values that must match the key.

UIStep

Represents a step that will be shown in the web interface.

Example

{
  "advanced": false,
  "name": "General configuration"
}

Attributes

advanced

Type: boolean

Defines if the step is an advanced one.

description

Type: string

Description of the step.

name [required]

Type: string

Name of the step.

parameters

Type: []uiparameter

List of parameters for this step.

ValidateUIParameter

Validates a list of UIParameter parameters.

Relations

POST /validateuiparameters

Validates some UI parameters.

Attributes

errors

Type: map[string]string

Contains the list of errors.

parameters

Type: []uiparameter

List of parameters to validate.

values

Type: map[string]interface{}

Contains the computed values.