IoT Access Control Service

The IoT Access Control service allows you to manage network access to IoT devices through APIs.

Setting Agent Known Assets

This API call provides a list of known IoT assets and their properties to the Nano Agent.

API Call

POST http://<localhost address of the IoT device>:5666/set-assets

Request Body (application/json) schema

Copy

{ 
   "assets": [ 
      { "ttl": < Integer - Asset TTL in Seconds >, 
        "confidence": < Integer - Asset Confidence >, 
        "name": <String - Asset Name>, 
        "mainAttributes": { 
          "ip": <String - Asset IP>
        }, 
      "attributes": { 
      "<1st Attribute Key>": <String - 1st Attribute Value>, 
      "<2nd Attribute Key>": <String - 2nd Attribute Value>, 
       . 
       . 
       . 
     } 
    }, 
     . 
     . 
     . 
   ] 
}

Parameter	Type	Description
ttl	Integer	Reserved for future use.
confidence	Integer	Reserved for future use.
name	String	Name of the asset.
mainAttributes	Object	Object that includes properties to identify the asset. The object: Must include only the asset IP address Must not include any other fields
attribute	Object	Object that includes custom key-value pairs indicating attributes specific to the asset. For example, "location": "London" You can use the asset attributes in the Access Control rulebase as a Source or a Destination.

Request body example:

Copy

{
    "assets": [
        {
            "ttl": 100,
            "confidence": 100,
            "name": "Blue server",
            "mainAttributes": {
                "ip": "40.40.40.2"
            },
            "attributes": {
                "color": "blue",
                "location": "London",
                "stage": "devel"
            }
        },
        {
            "ttl": 100,
            "confidence": 100,
            "name": "Green server",
            "mainAttributes": {
                "ip": "40.40.40.3"
            },
            "attributes": {
                "color": "blue",
                "stage": "production"
            }
        },
        {
            "ttl": 100,
            "confidence": 100,
            "name": "Client",
            "mainAttributes": {
                "ip": "40.40.40.1"
            },
            "attributes": {
                "group": "auth-clients",
                "color": "red"
            }
        }
    ]
}

Setting Agent Access Control Rulebase

This API call allows you to set a new access control rulebase for the Nano Agent. It accepts two types of rules, one for incoming traffic and one for outgoing traffic. Incoming rules will match against packets received by the agent, while outgoing rules will match against packets sent by the agent.

Note - This action always overrides the current rulebase, ensuring that the agent's traffic is as per the latest defined rules.

API Call

POST http://<localhost address of the IoT device>:5666/set-access-control-policy

Request Body (application/json) schema

Copy

{
    "defaultAllow": <Boolean - Allow connection not listed in the rulebase>,
    "incomingRules": [
        {
            "name": <String - Rule name, will appear in relevant logs>,
            "source": [
                <String - Identifier for the traffic client>
            ],
            "destinationPort": [
                <String - the server port>
            ],
            "sourcePort": [
                <String - the server port>
            ],
            "action": <String - rule action>,
            "trigger": [
                <String - rule trigger>
            ]
        },
        .
        .
        .
    ],
    "outgoingRules": [
        {
            "name": <String - Rule name, will appear in relevant logs>,
            "destination": [
                <String - Identifier for the traffic server>
            ],
            "destinationPort": [
                <String - the server port>
            ],
            "sourcePort": [
                <String - the server port>
            ],
            "action": <String - rule action>,
            "trigger": [
                <String - rule trigger>
            ]
        },
        .
        .
        .

    ]
}

Rule Properties

Property	Type	Description
defaultAllow	Boolean	True - Access control accepts all traffic not dropped by the incoming/outgoing rules. False - Access control drops all traffic not accepted by the incoming/outgoing rules.
name	String	Name of the rule. It appears in logs associated with the rule.
source	Vector of strings	A list of identifiers that are matched against the client. You can construct each identifier from several logical AND conditions separated by &&. Each condition in the identifier is composed of a <KEY>:<VALUE> pair. A Condition Key can be one of these: ipAddress - Value can be a specific IP address, IP network, or a range of IP addresses. domainName - Domain name to which traffic is allowed. Any other string - The agent searches for the traffic in the known assets lists and tries to match the Key to one of the assets' attributes. The agent performs an explicit OR between the identifiers in the list. Example: "source": ["Key1:Val1&&Key2:Val2", "Key1:Val3"] will be matched if the client of the connection has: ("Val1" for "Key1" AND "Val2" for "Key2") OR ("Val3" for "Key1") If this parameter is empty, any client matches.
destination	Vector of strings	A list of identifiers that are matched against the server. The format is the same as the source field.
destinationPort	Vector of strings	A list of ports that are matched against the server port. Format of each port is `<Port Number>/<IP Protocol>`. The agent performs an explicit OR between the ports in the list. If this parameter is empty, any port matches.
sourcePort	Vector of strings	A list of ports that are matched against the server port. Format of each port is `<Port Number>/<IP Protocol>`. The agent performs an explicit OR between the ports in the list. If this parameter is empty, any port matches.
action	String	The action to perform when the traffic matches the rule. The supported actions are: accept drop
triggers	Vector of strings	A list of triggers to perform when the traffic matches the rule. The possible triggers are: accept logs - Agent sends Accept logs for connections that matched the rule. drop logs - Agent sends Drop logs for connections that matched the rule.

Request body example:

Copy

{
    "defaultAllow": true,
    "incomingRules": [
        {
            "name": "Allow traffic from red",
            "source": [
                "color:red"
            ],
            "destinationPort": [
            ],
            "sourcePort": [
            ],
            "action": "accept",
            "trigger": [
                "accept logs"
            ]
        },
        {
            "name": "Allow traffic ipranges on port 80",
            "source": [
                " ipAddress:10.10.10.2-10.10.10.200"
            ],
            "destinationPort": [
                "80/6"
            ],
            "sourcePort": [
            ],
            "action": "accept",
            "trigger": [
                "accept logs"
            ]
        },
        {
            "name": "Drop from certain IPs",
            "source": [
                "color:blue&& ipAddress :172.55.12.0/24",
                " ipAddress:55.212.33.0-55.212.33.70"
            ],
            "destinationPort": [
            ],
            "sourcePort": [
            ],
            "action": "drop",
            "trigger": [
            ]
        }
    ],
    "outgoingRules": [
        {
            "name": "Allow traffic to red",
            "destination": [
                "color:red"
            ],
            "destinationPort": [
            ],
            "sourcePort": [
            ],
            "action": "accept",
            "trigger": [
                "accept logs"
            ]
        }
    ]
}

Logs and Events

The Nano Agent saves the logs locally in /var/log/nano-agent/cp-nano-iot-access-control.log

Log format

Copy

{
 "eventTime": <String>, 
 "eventName": <String>, 
 "eventSeverity": <String>, 
 "eventPriority": <String>, 
 "eventType": <String>, 
 "eventLevel": <String>, 
 "eventLogLevel": <String>, 
 "eventAudience": <String>, 
 "eventAudienceTeam": "", 
 "eventFrequency": <Integer>, 
 "eventTags": [
 <String>
 ],
 "eventSource": { "agentId": <String>,
 "eventTraceId": <String>, 
 "eventSpanId": <String>, 
 "issuingEngineVersion": <String>, 
 "serviceName": <String>
 },
 "eventData": { 
 "logIndex": <Integer>,
  .
  .
  .
 }
}

Connection Log

This log indicates whether the Access Control agent accepted or dropped a connection. The log includes:

Field	Type	Description
ruleId	String	ID of the rule that matched with the traffic.
ruleName	String	Name of the rule that matched with the traffic.
securityAction	String	Verdict of the rule that matched with the traffic.
interfaceName	String	Name of the interface from which the traffic arrived.
sourceIp	String	Connection Source IP address.
sourcePort	String	Connection Source port.
destinationIp	String	Connection Destination IP address.
destinationPort	String	Connection Destination port.
ipProtocol	String	Connection IP protocol: TCP UDP
tcpHandshake	String	Indicates which part of the TCP handshake was completed, if the matched connection is a TCP connection: `s--` indicates only the client TCP [SYN] `ss-` indicates client and server TCP [SYN] `ssa` indicates the entire TCP handshake

Connection log example

Copy

{
 "eventTime": "2022-10-30T16:16:12.028",
 "eventName": "Connection rulebase hit", 
 "eventSeverity": "High",
 "eventPriority": "High", 
 "eventType": "Event Driven", 
 "eventLevel": "Log", 
 "eventLogLevel": "info", 
 "eventAudience": "Security", 
 "eventAudienceTeam": "", 
 "eventFrequency": 0, 
 "eventTags": [
 "Informational"
 ],
 "eventSource": { 
 "agentId": "Unknown", 
 "eventTraceId": "",
 "eventSpanId": "", 
 "issuingEngineVersion": "a840cce",
 "serviceName": "IoT Access Control Service"
 },
 "eventData": { 
 "logIndex": 13,
 "ConnectionLog": "ruleId='2' ruleName='rule12' securityAction='Accept' interfaceName='ens33' 
 sourceIp='192.168.146.129' sourcePort='22' destinationIp='192.168.146.1' destinationPort='64022' 
 ipProtocol='TCP' tcpHandshake='ss-' "
  }
}