Introduction¶

The naming library is used by the Aerleon system to parse definitions of network and service data. These definitions are based on 'tokens' that are used in the high-level policy language.

Basic Usage¶

Create a directory to hold the definitions files

mkdir /path/to/definitions/directory

Create a definition YAML file

cat > /path/to/definitions/directory/definitions.yaml
networks:
  INTERNAL:
    values:
      - address: 10.0.0.0/8
        comment: "RFC1918"
      - address: 172.16.0.0/12
        comment: "RFC1918"
      - address: 192.168.0.0/16
        comment: "RFC1918"
  WEB_SERVERS:
    values:
      - address: 200.3.2.1/32
        comment: "webserver-1"
      - address: 200.3.2.4/32
        comment: "webserver-2"
  MAIL_SERVERS:
    values:
      - address: 200.3.2.5/32
        comment: "mailserver-1"
      - address: 200.3.2.6/32
        comment: "mailserver-2"
services:
  MAIL_SERVICES:
    - name: SMTP
    - name: ESMTP
    - name: SMTP_SSL
    - name: POP_SSL
  SMTP:
    - port: 25
      protocol: tcp
  DNS:
    - port: 53
      protocol: tcp
    - port: 53
      protocol: udp
  HTTP:
    - port: 80
      protocol: tcp
      comment: "web traffic"
  SMTP_SSL:
    - port: 465
      protocol: tcp
  ESMTP:
    - port: 587
      protocol: tcp
  POP_SSL:
    - port: 995
      protocol: tcp
^D

Create a Naming object

from aerleon.lib import naming
defs = naming.Naming('/path/to/definitions/directory')

Access Definitions From the Naming Object

defs.GetNet('INTERNAL')
defs.GetService('MAIL')
defs.GetServiceByProto('DNS','udp')

Methods¶

Network Query Methods¶

Naming.GetNet¶

Expand a network token into a list of nacaddr.IPv4 or nacaddr.IPv6 objects.

Parameters:

Name	Type	Description	Default
`query`	`str`	Network definition token. May include comment text.	required

Returns:

Type	Description
`List[Union[IPv4, IPv6]]`	List of nacaddr.IPv4 or nacaddr.IPv6 objects

Raises:

Type	Description
`UndefinedAddressError`	Network token not defined
`EmptyDefinitionError`	No IP address values found for this network token

Naming.GetIpParents¶

Return network tokens that contain IP in query.

Parameters:

Name	Type	Description	Default
`query`	`str`	an ip string ('10.1.1.1') or nacaddr.IP object	required

Returns:

Type	Description
`List[str]`	A sorted list of unique parent tokens.

Naming.GetNetParents¶

Given a query token, return list of network definitions with that token.

Parameters:

Name	Type	Description	Default
`query`	`str`	a network token name.	required

Returns: A list of network definitions containing the token.

Naming.GetNetChildren¶

Given a query token, return list of network definitions tokens within provided token.

This will only return children, not descendants of provided token.

Parameters:

Name	Type	Description	Default
`query`	`str`	a network token name.	required

Returns:

Type	Description
`List[str]`	A list of network definitions tokens within this token.

Naming.GetFQDN¶

Expand a network token into a list of FQDN objects.

Parameters:

Name	Type	Description	Default
`query`	`str`	Network definition token. May include comment text	required

Returns:

Type	Description
`List[str]`	List of nacaddr.IPv4 or nacaddr.IPv6 objects

Raises:

Type	Description
`UndefinedAddressError`	Network token not defined
`EmptyDefinitionError`	No FQDN values found for this network token

Service Query Methods¶

Naming.GetService¶

Given a service name, return a list of associated ports and protocols.

Parameters:

Name	Type	Description	Default
`query`	`str`	Service name symbol or token.	required

Returns:

Type	Description
`List[str]`	A list of service values such as ['80/tcp', '443/tcp', '161/udp', ...]

Raises:

Type	Description
`UndefinedServiceError`	If the service name isn't defined.

Naming.GetServiceByProto¶

Given a service name, return list of ports in the service by protocol.

Parameters:

Name	Type	Description	Default
`query`	`str`	Service name to lookup.	required
`proto`	`str`	A particular protocol to restrict results by, such as 'tcp'.	required

Returns:

Type	Description
`List[str]`	A list of service values of type 'proto', such as ['80', '443', ...]

Raises:

Type	Description
`UndefinedServiceError`	If the service name isn't defined.

Naming.GetPortParents¶

Returns a list of all service tokens containing the port/protocol pair.

Parameters:

Name	Type	Description	Default
`query`	`str`	port number ('22') as str	required
`proto`	`str`	protocol name ('tcp') as str	required

Returns:

Type	Description
`List[str]`	A list of service tokens: ['SSH', 'HTTPS']

Raises:

Type	Description
`UndefinedPortError`	If the port/protocol pair isn't used in any

Naming.GetServiceParents¶

Given a query token, return list of services definitions with that token.

Parameters:

Name	Type	Description	Default
`query`	`str`	a service token name.	required

Returns: List of service definitions containing the token.

Data Loading Methods¶

Naming.ParseYaml¶

Load network and service definitions from YAML.

Parameters:

Name	Type	Description	Default
`file`	`str`	A string containing the file contents.	required
`file_name`	`str`	The original filename of the file.	required

Naming.ParseDefinitionsObject¶

Load network and service definitions from a Python object.

Parameters:

Name	Type	Description	Default
`file_data`	`Dict[str, str]`	A Python dict where file_data.networks contains network data and/or file_data.services contains service data.	required
`file_name`	`str`	The original filename of the file.	required