natlas

natlas - Network Atlas
Michael Laforest <mjlaforest at gmail dot com>

Automated discovery and diagram tools using SNMP, CDP, and LLDP.

# ./natlas-cli.py diagram -r 10.75.0.1 -o .\network.svg The above command will generate the diagram to the right.

Support

If you use any of these tools or find them useful please consider donating.

Donation Method	Address	QR Code
Bitcoin Cash (BCH)	1HSycjR3LAZxuLG34aEBbQdUSayPkh8XsH
Bitcoin (BTC)	1HY3jPYVfE6YZbuYTYfMpazvSKRXjZDMbS

About

natlas is a python application framework which includes a discovery engine, an API, and a front-end cli for running available modules.

For Users

The natlas-cli.py program allows you to browse and execute any natlas module, including, among others, the network discovery and diagram module.

For Developers

Copy docs/template_module.py to a new file in the modules/ directory. Edit the function mod_load() to set the name and help properties for your module. The entry function for any module is mod_entry(). When creating a new module, natlas will create a new object and pass it to mod_entry(). From there the natlas API is available and includes functions such as:

• discover_network()
• query_node()
• get_switch_vlans()

Once saved, your module will automatically be listed in natlas-cli.py list and runnable.

Modules

Network Discovery

The discovery process uses SNMP, CDP, and LLDP to discover the network topology and details about each node. Each discovered node will be evaluated against the discover ACL (defined in the config file) to determine how to proceed; the ACL may allow discovery, stop discovery here, or include it as a leaf in the diagram.

"discover" : [
    ACE1,
    ACE2,
    ...
    ACEn,
]

<permit|deny|leaf|include|;> < [host REGEX] | [ip CIDR] >

"discover" : [
    "deny ip 10.50.12.55",
    "deny host ^SEP.*",
    "permit ip 10.50.12.0/24",
    "leaf host ^Switch2$",
    "permit ip any"
]    

Command Reference

Diagram

# natlas-cli.py diagram -r <root IP>
                -o <output file>
               [-d <max depth>]
               [-c <config file>]
               [-t <diagram title>]
               [-C <catalog file>]

get-mac-table

# natlas-cli.py get-mac-table -n <node IP> -c <snmp v2 community> [-m <mac regex>] [-p <port regex>] [-v <vlan>]

get-arp-table

# natlas-cli.py get-arp-table -n <node IP> -c <snmp v2 community> [-s | -d] [-i <IP regex>] [-v <vlan regex>] [-m <mac regex>]

get-hosts

get-hosts can either collect information from a single node or can do a network discovery and collect information from all discovered nodes.

# natlas-cli.py get-hosts -r <root IP> -c <config file> [-o <csv file>] [-d <discovery depth>]

# natlas-cli.py get-hosts -n <node IP> [-r <router IP>] -C <snmp v2 community> [-v <vlan regex>] [-p <port regex>] [-o <csv file>]

tracemac

# natlas-cli.py tracemac -n <starting node IP> -m <MAC address>

Config

Configuration File

The configuration file defines common parameters in a JSON format.

{
    "snmp" : [
        { "community":"private",    "ver":2 },
        { "community":"public",     "ver":2 }
    ],
    "domains" : [
        ".company.net",
        ".company.com"
    ],
    "discover" : [
        "permit ip 10.0.0.0/8",
        "permit host Router[1,2]",
        "deny ip any",
    ],
    "diagram" : {
        "node_text_size" : 10,
        "link_text_size" : 9,
        "title_text_size" : 15,
        "get_stack_members" : 0,
        "get_vss_members" : 0,
        "expand_stackwise" : 0,
        "expand_vss" : 0,
        "expand_lag" : 1,
        "group_vpc" : 0
    }

}

Diagram block

Diagram

natlas will attempt to collect the following information and include it in the generated diagram:

• All devices (via CDP and LLDP)
• Interface names
• IP addresses
• VLAN memberships
• Etherchannel memberships (LACP only)
• Identify trunk links
• Identify switched links
• Identify routed links
• BGP Local AS
• OSPF Router ID
• HSRP Virtual IP
• HSRP Priority
• VSS Domain
• Stackwise membership
• VPC peerlink information

Diagram Formatting

• Nodes
  • Circle nodes represent layer 2 switches.
  • Diamond nodes represent layer 3 switches or routers.
  • If a node has multiple borders then either VSS or StackWise is enabled.
  • VSS - Will always have a double border.
  • StackWise - The number of borders denotes the number of switches in the stack.
  • If the configuration specifies, VSS/VPC/Stackwise nodes will be grouped in larger squares.
• Links
  • Links are shown with arrowed lines. The end with no arrow is the parent and the end with the arrow is the child, such that the arrangement is parent->child.
  • If a link says P:gi0/1 , C:gi1/4 then the parent node's connection is on port gi0/1 and the child node's connection is on port gi1/4.
  • If the link is part of an Etherchannel the etherchannel's interface name will also be shown. Since an etherchannel interface is locally significiant, a P: and C: will also be shown if available.

Examples

Diagram Example 1

Diagram Example 2

Diagram Example 3

get-hosts Example 1

tracemac Example 1

FAQ

Q1 - My diagram is too large. I only want to diagram part of my network.

Try changing the config discover ACL to narrow down the scope of your discovery. You can explicitly deny CIDR's or host name regex patterns if you do not want them included in your diagram.

Q2 - Where is the config file?

Create a new one with # natlas-cli.py newconfig > natlas.conf

Q3 - I need a diagram with less proprietary information. Can I get one without IPs or serial numbers?

You can change the text inside each node by editing the config option diagram\node_text. Below is an example that would produce a minimal information diagram:

"diagram" : {
    node_text = '<font point-size="10"><b>{node.name}</b></font><br />{node.ios}<br />{node.plat}'
}   

Q4 - How can I remove Cisco VoIP phones from my diagram?

"discover" : [
    "deny host ^SEP.*$"
]