v0.1.4 added ifinfo, modified error handling

CHANGES

@@ -97,6 +97,7 @@ v 0.1.4
     - covclassget
     - retryshortget
     - retrylongget
+    - ifinfo
    o modified devadd. User is allowed to submit a Card object or a physical index
    o removed hardcoded values for covclassset, retry(short|long)set, retsthreshet and
      fragrthreshset
@@ -111,4 +112,6 @@ v 0.1.4
    o added new functions from 0.1.3 and 0.1.4 to unittests
    o updated nl80211_h w/ additional constants included in kernel v 4 header
    o added propietary concept of set to netlink processing
-    - nl80211 appears to define a set of like-sized elements (see cipher_suites)
+    - nl80211 appears to define a set of like-sized elements (see cipher_suites)
+   o modified pyric exceptions
+    - imports errno codes into pyric, conforming how functions access error codes

README.md

@@ -66,13 +66,12 @@ halved.
 ATT, PyRIC accomplishes my core needs but it is still a work in progress. It
 currently pyw provides the following:
 * enumerate interfaces and wireless interfaces
-* identify a cards chipset and driver
+* identify a cards driver, chipset and manufacturer
 * get/set hardware address
 * get/set ip4 address, netmask and or broadcast
 * turn card on/off
-* get supported standards
-* get supported commands
-* get supported modes
+* get supported standards, commands or modes
+* get if info
 * get dev info
 * get phy info
 * get/set regulatory domain
@@ -158,8 +157,8 @@ To use PyRIC, see the examples folder or read throuhg PyRIC.pdf. However, for
 those impatient types:
 
 ```python
-import pyric          # pyric error and EUNDEF error code
-from pyric import pyw  iw functionality
+import pyric           # pyric errors
+from pyric import pyw  # iw functionality
 ```
 
 will import the basic requirements and unless otherwise stated is assumed for the
@@ -170,6 +169,21 @@ that these examples use one-time sockets.
 Although not all functions require root, we assume that the below have been
 executed with root permissions.
 
+Before proceeding with the examples, let's talk about pyric error handling. The
+pyric module imports the errorcodes found in the errno module as its own. The 
+pyric error subclasses EnvironmentError and all pyric errors are tuples of the 
+form t = (error code,error message).
+
+```python
+>>> try:
+...     #some pyric code
+... except pyric.error as e:
+...     #handle the error
+```
+
+Work is ongoing to help clarify some of the error messages returned by default
+by os.strerror for example. 
+
 ### a. System/Wireless Core Functionality
 These functions do not work with a specific device rather with the system.
 
@@ -298,6 +312,17 @@ and Fragmentation thresholds see http://resources.infosecinstitute.com/rts-thres
 #### iv. Getting Info On Your Card
 
 ```python
+>>> iinfo = pyw.ifinfo(w0)
+>>> for i in iinfo: print i, iinfo[i]
+... 
+mask 255.255.255.192
+driver iwlwifi
+hwaddr a0:88:b4:9e:68:58
+chipset Intel 4965/5xxx/6xxx/1xxx
+bcast 192.168.3.63
+inet 192.168.3.7
+manufacturer Intel Corporate
+>>>
 >>> dinfo = pyw.devinfo(w0)
 >>> for d in dinfo: print d, dinfo[d]
 ...

docs/PyRIC.tex

@@ -464,7 +464,7 @@ \subsubsection{One-time vs Persistent Sockets}
 \begin{lstlisting}[caption={Using Persistent Sockets},
                    label={lst:persistent},
                    language=Python]
- 1: import pyric                      # pyric error (and ecode EUNDEF)
+ 1: import pyric                      # pyric errors
  2: from pyric import pyw             # for iw functionality
  3: from pyric.lib import libnl as nl # for netlink sockets
  4:
@@ -911,7 +911,7 @@ \subsection{Constants}
 
 \subsection{Functions}
 \begin{enumerate}
-\item parse([opath]): returns a dict of oui:manufacturer key->value pairs stored
+\item load([opath]): returns a dict of oui:manufacturer key->value pairs stored
 in the text file at opath. If opath is not specified, uses the default
 \item fetch([opath]): retrieves oui.txt from the IEEE website, parses the files
 and stores the results in a PyRIC friendly format in opath. If opath is not 

examples/info.py

@@ -6,79 +6,85 @@
 """
 
 import argparse as ap
+import sys
 import pyric                           # pyric error (and ecode EUNDEF)
 from pyric import pyw                  # for iw functionality
-import pyric.utils.hardware as hw      # for chipset/driver
-from pyric.utils import ouifetch       # for oui dict
 from pyric.utils.channels import rf2ch # rf to channel conversion
 
-def execute(dev):
+def execute(dev,itype):
     # ensure dev is a wireless interfaces
     wifaces = pyw.winterfaces()
     if dev not in wifaces:
         print "Device {0} is not wireless, use one of {1}".format(dev,wifaces)
 
+    # get info dicts
     dinfo = pyw.devinfo(dev)
     card = dinfo['card']
     pinfo = pyw.phyinfo(card)
-    driver = hw.ifdriver(card.dev)
-    chipset = hw.ifchipset(driver)
+    iinfo = pyw.ifinfo(card)
 
-    manuf = hw.manufacturer(ouifetch.parse(),dinfo['mac'])
+    if itype == 'all' or itype == 'if':
+        msg = "Interface {0}\n".format(card.idx)
+        msg += "\tDriver: {0} Chipset: {1}\n".format(iinfo['driver'],iinfo['chipset'])
+        msg += "\tHW Addr: {0} Manufacturer: {1}\n".format(iinfo['hwaddr'],
+                                                           iinfo['manufacturer'])
+        msg += "\tInet: {0} Bcast: {1} Mask: {2}\n".format(iinfo['inet'],
+                                                           iinfo['bcast'],
+                                                           iinfo['mask'])
+        print msg
 
-    msg = "Device {0}\n".format(dev)
-    msg += "\tDriver: {0} Chipset: {1}\n".format(driver,chipset)
-    msg += "\tManufacturer: {0}\n".format(manuf)
-    msg += "\tifindex: {0}\n".format(card.idx)
-    msg += "\twdev: {0}\n".format(dinfo['wdev'])
-    msg += "\taddr: {0}\n".format(dinfo['mac'])
-    msg += "\tmode: {0}\n".format(dinfo['mode'])
-    msg += "\twiphy: {0}\n".format(card.phy)
-    if dinfo['mode'] == 'managed':
-        msg += "\tchannel: {0} ({1} MHz), width: {2}, CF: {3}\n".format(rf2ch(dinfo['RF']),
-                                                                        dinfo['RF'],
-                                                                        dinfo['CHW'],
-                                                                        dinfo['CF'])
-    else:
-        msg += "\tDevice not associated\n"
-    print msg
+    if itype == 'all' or itype == 'dev':
+        msg = "Device {0}\n".format(card.dev)
+        msg += "\tifindex: {0}\n".format(card.idx)
+        msg += "\twdev: {0}\n".format(dinfo['wdev'])
+        msg += "\taddr: {0}\n".format(dinfo['mac'])
+        msg += "\tmode: {0}\n".format(dinfo['mode'])
+        msg += "\twiphy: {0}\n".format(card.phy)
+        if dinfo['mode'] != 'managed': msg += "\tDevice not associated\n"
+        else:
+            msg += "\tchannel: {0} ({1} MHz), width: {2}, CF: {3} MHz\n".format(rf2ch(dinfo['RF']),
+                                                                                dinfo['RF'],
+                                                                                dinfo['CHW'],
+                                                                                dinfo['CF'])
+        print msg
 
-    msg = "Wiphy phy{0}\n".format(card.phy)
-    msg += "\tGeneration: {0}m Coverage Class: {1}\n".format(pinfo['generation'],
-                                                             pinfo['cov_class'])
-    msg += "\tMax # scan SSIDs: {0}\n".format(pinfo['scan_ssids'])
-    msg += "\tRetry Short: {0}, Long: {1}\n".format(pinfo['retry_short'],
-                                                    pinfo['retry_long'])
-    msg += "\tThreshold Frag: {0}, RTS: {1}\n".format(pinfo['frag_thresh'],
-                                                      pinfo['rts_thresh'])
-    msg += "\tSupported Modes:\n"
-    for mode in pinfo['modes']:
-        msg += "\t  * {0}\n".format(mode)
-    msg += "\tSupported Commands:\n"
-    for cmd in pinfo['commands']:
-        msg += "\t  * {0}\n".format(cmd)
-    msg += "\tSupported Frequencies:\n"
-    for rf in pinfo['freqs']:
-        msg += "\t * {0} ({1})\n".format(rf,rf2ch(rf))
-    #for ch in map(rf2ch,pinfo['freqs']):
-    #    msg += "\t  * {0}\n".format(ch)
-    msg += "\tSupported Ciphers:\n"
-    for cipher in pinfo['ciphers']:
-        msg += "\t  * {0}\n".format(cipher)
+    if itype == 'all' or itype == 'phy':
+        msg = "Wiphy phy{0}\n".format(card.phy)
+        msg += "\tGeneration: {0}m Coverage Class: {1}\n".format(pinfo['generation'],
+                                                                 pinfo['cov_class'])
+        msg += "\tMax # scan SSIDs: {0}\n".format(pinfo['scan_ssids'])
+        msg += "\tRetry Short: {0}, Long: {1}\n".format(pinfo['retry_short'],
+                                                        pinfo['retry_long'])
+        msg += "\tThreshold Frag: {0}, RTS: {1}\n".format(pinfo['frag_thresh'],
+                                                          pinfo['rts_thresh'])
+        msg += "\tSupported Modes:\n"
+        for mode in pinfo['modes']: msg += "\t  * {0}\n".format(mode)
+        msg += "\tSupported Commands:\n"
+        for cmd in pinfo['commands']: msg += "\t  * {0}\n".format(cmd)
+        msg += "\tSupported Frequencies:\n"
+        for rf in pinfo['freqs']: msg += "\t * {0} ({1})\n".format(rf,rf2ch(rf))
+        msg += "\tSupported Ciphers:\n"
+        for cipher in pinfo['ciphers']: msg += "\t  * {0}\n".format(cipher)
 
-    print msg
+        print msg
 
 if __name__ == '__main__':
     # create arg parser and parse command line args
     print "Wireless Device Info Display using PyRIC v{0}".format(pyric.__version__)
     argp = ap.ArgumentParser(description="Wireless Device Data")
     argp.add_argument('-d','--dev',help="Wireless Device")
+    argp.add_argument('-t','--type',help="Info type one of {all|if|dev|phy}")
     args = argp.parse_args()
     try:
-        dev = args.dev
-        if dev is None:
-            print "usage: python details.py -d <dev>"
-        else:
-            execute(dev)
+        dname = args.dev
+        infotype = args.type
+        if dname is None:
+            print "usage: python details.py -d <dev> [-t <itype>]"
+            sys.exit(0)
+        if infotype is None: infotype = 'all'
+        if infotype not in ['all','if','dev','phy']:
+            print "usage: python details.py -d <dev> [-t one of {all|if|dev|phy}]"
+            sys.exit(0)
+        execute(dname,infotype)
     except pyric.error as e:
         print e

pyric/__init__.py

@@ -32,6 +32,8 @@
   changes:
    See CHANGES in top-level directory
 
+ WARNING: DO NOT import *
+
 """
 
 __name__ = 'pyric'
@@ -43,21 +45,29 @@
 __email__ = '[email protected]'
 __status__ = 'Production'
 
-from os import strerror
-
-# all exceptions are tuples t=(error code,error message)
-# we use errno.errocodes and use codes < 0 as an undefined error code
-EUNDEF = -1
+# define pyric exceptions
+#  all exceptions are tuples t=(error code,error message)
+#  we use error codes defined in errno, adding -1 to define the undefined error
+#  EUNDEF. I don't like importing all from errno but it provides conformity in
+#  error handling i.e modules using pyric.error do not need to call pyric.EUNDEF
+#  and errno.EINVAL but can call pyric.EUNDEF and pyric.EINVAL
+EUNDEF = -1                # undefined error
+from errno import *        # make all errno errors pyric errors
+errorcode['EUNDEF'] = -1   # add ours to errorcode dicts
 class error(EnvironmentError): pass
-
-def perror(e):
-    """
-    :param e: error code
-    :returns: string description of error code
-    """
-    # anything less than 0 is an unknown
-    return strerror(e)
-
+# BELOW IS STILL A WORK IN PRGORESS
+def strerror(errno):
+    import os
+    if errno < 0: return "Undefined error"
+    elif errno == EPERM: return "Superuser privileges required"
+    elif errno == EINVAL: return "Invalid parameter"
+    else:
+        return os.strerror(errno)
+
+# for setup.py use
+# redefine version for easier access
+version = __version__
+# define long description
 long_desc = """
 # PyRIC 0.1.4: Python Radio Interface Controller
 ## Linux wireless library for the Python Wireless Developer and Pentester

pyric/net/if_h.py

@@ -287,6 +287,6 @@ def ifreq(ifrn,ifru=None,param=None):
         else:
             raise AttributeError("ifru {0} not supported".format(ifru))
     except (TypeError,IndexError):
-        raise AttributeError("param is invalid")
+        raise AttributeError("parameters are invalid")
 
     return ifr