The topology is built from networks and routers. A router and a network are connected by an interface. Networks may have any number of hosts, which are located inside the network.

Routers may be managed or unmanaged. For a managed router, NetSPoC generates access control lists which control what traffic can pass this router and what traffic is blocked. The whole topology is partitioned into different security domains by managed routers.

Special network objects called 'any' objects and 'every' objects may be defined which denote all network objects in a security domain.

General syntax

All network objects and groups have a typed name like <type>:<name>.

<name> is build from one ore more alphanumerical and underscore characters. The current locale settings are used, i.e. accented characters are allowed for european locale settings.

<ip-adr> denotes an IP address. Currently NetSPoC handles IP v4 addresses n.n.n.n with 0 <= n <= 255

<interface_name> may contain any characters, even interspersed whitespace. Currently characters from [;,=] are not allowed, since we use them as delimiters.

<int> is an integer

Meta symbols in syntax definitions below:

<..> denote something defined elsewhere
[..] denotes an optional part
{{..|..}} denotes alternatives.
Note: single { and } characters stand for themselves.
... * means any number of the left part

Network Definition

Syntax

  network:<name> = {
     {{
         [ route_hint; ]
	 [ subnet_of = network:<name>; ]
         ip = <ip-adr>; mask = <ip-adr>; 
         <host definition> *
     |
         unnumbered
     }}
  }

A network is described by an ip address and a mask or
may alternatively be marked as unnumbered.
It may contain any number of host definitions.
Unnumbered networks must have no host definitions at all.
If used as source or destination of a rule, the ip/mask is used directly for generating ACLs.
An unnumbered network must not be used in rules.
All networks must be disjunct if option 'strict_subnets' is active. Exceptions must be declared explictly:
- route_hint: This network may enclose other networks, but it must not have host definitions.
- subnet_of: The enclosing network must be stated explicitly.
This may be useful for a large topology, where a network may easily be redefined by mistake.

Host definition

Syntax

  <host definition> ::=
  {{
        host:<name> = { ip = <ip-adr>, ...; }
  |
        host:<name> = { range = <ip-adr> - <ip-adr>; }
  }}

A host may only be defined inside a network definition.
It has one or more IP addresses or
alternatively an ip address range with first address < second address
IP addresses must match ip/mask of the surrounding network.
If used as source or destination of a rule, one ACL entry is generated for each IP address.
NetSPoC tries to automatically convert successive IP addresses from one or multiple hosts of a common network to an IP range.
During code generation, an IP range is split into a number of subnetworks which cover the range. One ACL entry is generated for each subnetwork.

Router definition

Syntax

  <router definition> ::=
  router:<name> = {
     {{
        managed; 
        model = <name>;
        static_manual;
	<complete interface definition> *
     |
        [ model = <name>; ]
        {{ <interface definition> | <short interface definition> }} *
     }}
  }

Managed routers need to be precisely described since this information is needed for code generation later.
The router model is used to generate correct code for different router models.
Currently three models are supported:
- PIX for Cisco PIX firewalls
- IOS_FW for Cisco IOS routers with statefull inspection
- IOS for stateless Cisco IOS
Note: IOS_FW was named IOS before NetSPoC version 1.3
A PIX firewall may be marked as 'static_manual' if no 'static' commands should be generated. We use this
- as a workaround for missing NAT functionality of NetSPoC and
- if we know, that incoming traffic is only allowed, after some outgoing connection has been established.
A Router may have any number of interface definitions.
For unmanaged routers, almost all attributes are optional.
If used as source or destination of a rule, a router is handled like a group of its interfaces.

Interface definition

Syntax

 <complete interface definition> ::=
 interface:<name> = {
         {{ ip = <ip-adr>, ...; | unnumbered; }}
         hardware = <interface_name>;
         [ disabled ; ]
 }

 <interface definition> ::= 
 interface:<name> = {
         {{ ip = <ip-adr>, ...; | unnumbered; }}
         [ hardware = <interface_name>; ]
         [ disabled ; ]
 }

 <short interface definition> ::=
 interface:<name>;

Interfaces have no name of their own; instead a network name is used to indicate that the interface is linked to a network of the same name.
An interface may have one or more IP addresses. All of them must match the IP/mask of the corresponding network.
An unnumbered interface must only be linked to an unnumbered network.
The 'hardware' attribute indicates, which hardware interface the router belongs to.
Multiple interfaces may belong to the same hardware interface.
An interface may be marked as disabled. See Disabling part of the topology below.
For interface definitions of unmanaged routers almost all attributes may be left out.
If a network is linked to a short interface definition, it must not be linked to any other interface. We need this requirement for getting all routing entries generated.
If used as source or destination of a rule an interface is handled like a host.

'Every' object definition

Syntax

 every:<name> = { link = {{ network:<name>; | router:<name>; }} }

An 'every' definition is equivalent to a group of all networks of a security domain.
It must not be linked to a managed router.

'Any' object definition

Syntax

 any:<name> = { link = {{ network:<name>; |  router:<name>; }} }

An 'any' definition is used to represent all networks of a security domain.
It must not be linked to a managed router.
At most one 'any' object can be defined for a security domain.
Generated ACLs use 'any' (i.e. network 0.0.0.0/0.0.0.0) to prevent enumeration of all networks of a security domain.
NetSPoC generates additional deny rules to prevent intervening networks getting undesired access.
See Handling of 'any' objects for details.

Referencing network objects

Syntax

 <network object> ::=
 {{
   host:<name> 
 | network:<name> 
 | router:<name> 
 | interface:<name>.<name> 
 | any:<name> 
 | every:<name>
 | group:<name> 
 }}

Network objects are referenced in groups or as source or destination of rules.
When referencing interfaces, we need to use a different syntax than for interface definitions: the router name followed by a network name.

Groups of network objects

Syntax

 group:<name> = <network object> *;

A group may be empty
A group may be defined by means of other groups

Services

Syntax

 service:<name> = 
 {{
   ip 
 | tcp [<range> ->] <range>
 | udp [<range> ->] <range>
 | icmp [<int_1>[/<int_2>]] 
 | proto <int> 
 }} ;

with

<range> ::= [<int_1>[-<int_2>]]

tcp, udp

A <range> denotes a tcp/udp port range
A <range> consisting of only one number denotes a single port
An empty <range> is equivalent with the full range of all ports 1 - 65535
If only one <range> is given, it describes the destination port
If two <range>s are given, they describe source and destination port
0 < <int_1> <= <int_2> <= 65535

icmp

<int_1>, <int_2> denote icmp type and code
0 <= <int_1>,<int_2> <= 255

protocol

<int> is a IP protocol number
0 < <int> <= 255

For describing a tcp connection between client and server, only one rule is needed with client as source. The packets back from the destination are allowed implicitly.
Similar to tcp connections, only one rule is needed to let udp packets pass from source to destination and back.
When using service "ip" in a rule, currently only packets from source to destination are allowed. But stateful packet filters let pass answer packets for tcp connections anyway. To get a unified handling for tcp, udp and ip for stateful and stateless packet filters, we might change this in the future, to let ip packets pass in both directions, with only one rule.

Groups of services

Syntax

  servicegroup:<name> = <service> *;

with

  <service> ::= {{ service:<name> | servicegroup:<name> }}

A servicegroup may be empty.
A servicegroup may be defined by means of other servicegroups.

Rules

Syntax

  <rule> ::=
  {{ permit | deny }}
        src = <obj1>, ..,<obj_n>;
        dst = <obj1>, ..,<obj_n>;
        srv = <srv1>, ..,<srv_n>;

Order of rules doesn't matter.
Deny rules override all permit rules.

Disabling part of the topology

An interface may be explicitly marked as disabled. This implicitly marks all network objects as disabled, that are directly or indirectly connected to this interface. All occurences of disabled network objects in groups and rules are silently discarded.

Handling of 'any' objects

The meaning of 'any' is different in a NetSPoC rule from that in an ACL. For NetSPoC, any:X means "any network object of the security domain where any:X is located". For an ACL which filters incoming traffic of an interface, any (i.e. 0.0.0.0/0.0.0.0) means "any network object beyond the interface where the ACL is applied to".

as source:: any data object connected directly or indirectly with this interface.
as destination:: any data object lying behind the router where the interface belongs to.

PIX security levels

PIX firewalls have a security level associated wih each interface. We don't want to expand our syntax to state them explicitly, but instead we try to derive the level from the interface name. It is not neccessary the find the exact level; what we need to know is the relation of the security levels to each other.

Automatic deletion of redundant rules

to be done ...

Generated Code

ACL
Routing
Static commands for PIX

Supported devices

PIX (only versions supporting access-lists, i.e. >= 5.x)
Cisco IOS with firewall feature set
Cisco IOS without firewall feature set (untested)