Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mteg/braa

Ultra-fast SNMPv1/v2 stack. Get/set/walk tens of thousands of hosts at once.
https://github.com/mteg/braa

Last synced: 13 days ago
JSON representation

Ultra-fast SNMPv1/v2 stack. Get/set/walk tens of thousands of hosts at once.

Awesome Lists containing this project

README 

        

1. OVERVIEW



  Braa is a mass snmp scanner. The intended usage of such a tool is of course 

making SNMP queries - but unlike snmpget or snmpwalk from net-snmp, it is able

to query dozens or hundreds of hosts simultaneously, and in a single process.

Thus, it consumes very few system resources and does the scanning VERY fast.

  

  Braa implements its OWN snmp stack, so it does NOT need any SNMP libraries

like net-snmp. The implementation is very dirty, supports only several data

types, and in any case cannot be stated 'standard-conforming'! It was designed

to be fast, and it is fast. For this reason (well, and also because of my

laziness ;), there is no ASN.1 parser in braa - you HAVE to know the numerical

values of OID's (for instance .1.3.6.1.2.1.1.5.0 instead of system.sysName.0).



2. REQUIREMENTS

  

  * an *IX system implementing BSD sockets and some POSIX syscalls

  * large ARP table - if you plan to query thousands of hosts, make

    sure your system is capable of managing thousands of ARP entries,

    for instance tune the gc_thresh values in Linux...



  * it is also good to have a complete SNMP package installed somewhere,

    because braa accepts only numerical OID's, so you may need to make

    use of snmptranslate.



  Braa is not at all portable - it was tested only on several setups:

  * Linux (shaerrawedd 2.4.19-xfs #7 Fri Oct 4 18:18:38 CEST 2002 i686 unknown)

  * FreeBSD (venom 4.6.2-RELEASE-p10 FreeBSD 4.6.2-RELEASE-p10 #0: Tue Mar 25

           12:59:45 CET 2003     root@venom:/usr/src/sys/compile/VENOM-3  i386)

  * OpenBSD (pantera 3.3 PANTERA#0 i386)



  With minor adjustments, braa should also work under SunOS, and actually, any

  POSIX-compilant UNIX system. The problem is I just do not have access to any

  machines running something different than BSD or Linux.



3. INSTALLATION



  * edit Makefile and uncomment the right setting for your OS

  * do a 'make'

  * copy the 'braa' binary into a desired place.

   

4. USAGE



    Braa is controlled from the command line using a standard

  getopt approach:

  

  braa [-2] [-v] [-t ] [-f ] [-a 



    As you can see, the list of queries to make is specified as a

  commandline argument. The syntax of the query list follows:

  

    [community@]host1[-host2][:port]:query1[/id][,query2[/id][,query3[/id]...]]



    Well, this seems quite complicated, but let us have a look at few examples:

	

	10.253.101.1:.1.3.6.1.2.1.1.6.0

	10.253.101.1:.1.3.6.1.2.1.1.*

	10.253.101.1-10.253.101.50:.1.3.6.1.2.1.1.6.0

	10.253.101.1:.1.3.6.1.2.1.1.4.0/ContactPerson,.1.3.6.1.2.1.4.20.*/RoutingTable

	[email protected]:.1.3.6.1.2.1.1.6.0=sMy network

	

	The strings after the last colon are the actual queries to be made. To make

  a GET query (to retrieve a value under a specific Object ID, just what snmpget

  does), one specifies only the Object ID. As it was stated in the Overview,

  braa accepts only numerical OIDs, and this is why you need the fully-featured

  SNMP package: to translate OIDs. You can get numerical OIDs from symbolic ones

  using the 'snmptranslate' command from a complete SNMP package, usually by

  issuing something like:



    $ snmptranslate -mall system.sysLocation.0

    .1.3.6.1.2.1.1.6.0



    So, the first example is a GET query on object .1.3.6.1.2.1.1.6.0 - which is

  just system.sysLocation.0. Running 'braa 10.253.101.1:.1.3.6.1.2.1.1.6.0'

  would return something like:

  

    10.253.101.1:25ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland



    Which means 10.253.101.1 answered in about 25 ms and claimed, that

  system.sysLocation.0 contains the string "Elsat HFC (...)". Keep on mind

  that the response time is in fact very inaccurate...



    Another query type is the WALK query. WALK queries make braa traverse

  the object tree hierachy ,,below'' a specified object, like snmpwalk

  does. The second example:

	10.253.101.1:.1.3.6.1.2.1.1.*

    is a WALK query on the 'system' (.1.3.6.1.2.1.1) object; the output

  would look like:



    10.253.101.1:26ms:.1.3.6.1.2.1.1.1.0:Thomson DOCSIS Cable Modem <>

    10.253.101.1:24ms:.1.3.6.1.2.1.1.2.0:.1.3.6.1.4.1.2863.390.2.1.51.2.4

    10.253.101.1:28ms:.1.3.6.1.2.1.1.3.0:726500

    10.253.101.1:28ms:.1.3.6.1.2.1.1.4.0:Mateusz Golicz MG452-RIPE 

    10.253.101.1:27ms:.1.3.6.1.2.1.1.5.0:Thomson 390 DOCSIS CM, DOCSIS 1.1 MODE

    10.253.101.1:27ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland

    ...

    

	To query 50 hosts, from 10.253.101.1 to 10.253.101.50 for

  system.sysLocation.0 one could of course issue something like:



    braa 10.253.101.1:.1.3.6.1.2.1.1.6.0 10.253.101.2:.1.3.6.1.2.1.1.6.0 ...



    ... but it is much more comfortable to specify a host range instead a single

  host in the query list specification, like in the third example:



    braa 10.253.101.1-10.253.101.50:.1.3.6.1.2.1.1.6.0

  

    And as usually, the output: 

	

	10.253.101.47:53ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland

    10.253.101.46:55ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland

    10.253.101.1:56ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland

    10.253.101.42:84ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland



    As you can see in the next example:



    10.253.101.1:.1.3.6.1.2.1.1.4.0/ContactPerson,.1.3.6.1.2.1.4.20.*/RoutingTable



    ... a comma character is used to separate queries in case one wants to

  specify more queries in a query list. The example also shows how to make

  advantage of query IDs. The IDs (after a slash) do not affect the querying

  process itself, but they are just printed before appropiate lines of output:

  

    ContactPerson:10.253.101.1:25ms:.1.3.6.1.2.1.1.4.0:Mateusz Golicz MG452-RIPE 

    RoutingTable:10.253.101.1:29ms:.1.3.6.1.2.1.4.20.1.1.10.253.101.1:10.253.101.1

    RoutingTable:10.253.101.1:23ms:.1.3.6.1.2.1.4.20.1.1.127.0.0.1:127.0.0.1

    RoutingTable:10.253.101.1:26ms:.1.3.6.1.2.1.4.20.1.1.192.168.100.1:192.168.100.1

    RoutingTable:10.253.101.1:27ms:.1.3.6.1.2.1.4.20.1.2.10.253.101.1:2



    ... so it is easier to split and parse braa output using automated

  tools like awk.



    The last example demonstrates the SET query: 



	[email protected]:.1.3.6.1.2.1.1.6.0=sMy network

	

	This attempts to set .1.3.6.1.2.1.1.6.0 (which is again my

  favourite system.sysLocation.0) at hosts 10.253.101.1 up to 50 to

  'My network'. The "s" before the right value specifies the value type;

  braa supports currently:

     s String      (eg. "sMy Network")

	 a IP Address  (eg. "a10.253.100.1")

	 i Integer     (eg. "i10")

	 o OID         (eg. "o.1.3.6.1.2.1.4.20.1.1.10.253.101.1")

	If the type prefix is not specified (eg. the character after

  '=' is none of the above), braa attempts to auto-detect the type.



	The 'private@' part before the host range of course sets the

  SNMP community name for the transaction to 'private'.



    ... and that seems to be all about the query format. You may

  also make a file containing the query lists one by line instead

  of providing them as commandline arguments. Use the -f option to

  load queries from such a list. Other options are:



    -r      retry count: try making each query  times 

  before giving up. By default, the retry count is set to 3.

  

    -a    deadline time; makes braa quit after  

  seconds, independent on what happens. 



    -2             SNMPv2C - braa will introduce itself as a SNMPv2C

  agent (but in fact the packets are always constructed according

  to SNMP1 RFCs). This is useful for retrieving data from objects

  that hold data types not covered by the SNMP1 specification - at

  the moment the only such supported data type is Counter64.

  

    -t    Wait  seconds for responses. When

  nothing happens for the given time (there are no more messages

  to send and nothing more is received), braa quits. The default

  is 2 seconds.

  

    -d      Makes braa wait for  microseconds after

  sending each packet. Useful if the bandwidth between you and

  the devices you are querying is limited - see the short explanation

  on how braa works below.

  

    -h             Help, shows a short summary of this manual ;)



5. REMARKS



    Braa takes full advantage of the possibility to make serveral SNMP

  queries using a single SNMP packet and will never send more than one

  packet per a query type (of course except retries if there was no answer)

  to a host (btw, see LIMITATIONS). This means that the following commands:

  

     braa 10.253.101.1:.1.3.6.1.2.1.1.6.0 10.253.101.1:.1.3.6.1.2.1.1.5.0

     braa 10.253.101.1:.1.3.6.1.2.1.1.5.0,.1.3.6.1.2.1.1.6.0



    Do EXACTLY the same: a SINGLE packet requesting information on

  .1.3.6.1.2.1.1.5.0 and .1.3.6.1.2.1.1.6.0 is sent to 10.253.101.1.

  

    Braa sends queries for every host on the query list, meanwhile

  listening for answers (non-blocking sockets are used for this

  purpose). Every upcoming answer is immediately decoded and

  outputted. After queries for all hosts have been sent, it waits

  20 ms, and then every host that did not answered in the first pass is

  sent the query again. The passes continue, until the retry count

  (specified using the -r option) is achieved or until all the hosts

  have answered. In the first case, braa waits then for any delayed

  messages for 2 seconds (this timeout might be changed by the -t option).



    Each time a packet is sent, braa might wait for a short period so

  as not to flood the link to its SNMP peers. This is controlled by the

  -d option.

  

    When querying multiple hosts always make sure your ARP table

  can hold enough entries (eg. you might have to adjust

  /proc/sys/net/ipv4/neigh/default/gc_thresh* under Linux).



6. BUGS AND LIMITATIONS



  * the only supported datatypes are: integer (gauge, counter, timeticks, etc.)

    counter64, string, ipaddress, OID. Of course you are free to modify

	braaasn.c/braaasn.h to support more types...

  * braa will never send more than 1500 bytes (or a single packet) to a host

    in a single try. Thus the number of queries that might be sent to a single

    host is limited. Additionally, if you reach the limit by specifying too many

    queries, braa will terminate the whole scanning process... I can't tell

    what the limit exactly is, it just depends on many factors (mainly, the

    length of OIDs), anyway, 15 queries per hosts sounds dangerous, and better

    try not to exceed this number.

  * it is impossible to specify FQDN hostnames - you always have to give IP

    addresses of hosts... well, I think it'll be corrected in future

    versions, if there will be ones.



7. AUTHORS, ACKNOWLEDGEMENTS



  Mateusz 'mteg' Golicz



8. LICENSE



  The package is licensed on GNU General Public License. See COPYING file.