[Autosec-devel] sonar/src mutex.h,1.2,1.3 plugin.h,1.46,1.47 types.h,1.21,1.22

[red0x <re...@us...>]

Update of /cvsroot/autosec/sonar/src
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10223/src

Modified Files:
	mutex.h plugin.h types.h 
Log Message:
Major documentation update, more to come.

Index: mutex.h
===================================================================
RCS file: /cvsroot/autosec/sonar/src/mutex.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** mutex.h	13 Apr 2004 03:42:08 -0000	1.2
--- mutex.h	5 May 2004 08:01:30 -0000	1.3
***************
*** 24,31 ****
--- 24,39 ----
  #include <pthread.h>
  
+ /*! \struct sonar_mutex_t
+ 	\brief Debuggable mutex
+ 	
+ 	This is a pthread mutex with some extra debugging information.
+ */
  typedef struct
  {
+ 	//! pthread mutex
      pthread_mutex_t mutex;
+ 	//! Mutex identifier
      char id[80];
+ 	//! Who has this mutex locked
      char *locked_by;
  } sonar_mutex_t;

Index: types.h
===================================================================
RCS file: /cvsroot/autosec/sonar/src/types.h,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** types.h	13 Apr 2004 03:42:08 -0000	1.21
--- types.h	5 May 2004 08:01:30 -0000	1.22
***************
*** 73,92 ****
  #endif // TIME_WITH_SYS_TIME
  
- /**
-   * @struct sa
-   * Socket Address
-   * This needs to be removed
-   */
- struct sa
- {
-     /** Socket Family */
-     unsigned short family,
-     /** Destination Port */
-       dport;
-     /** IP Address */
-     unsigned int addr;
-     /** Padding (zeros) */
-     unsigned char zero[8];
- };
  
  typedef unsigned short bool;
--- 73,76 ----

Index: plugin.h
===================================================================
RCS file: /cvsroot/autosec/sonar/src/plugin.h,v
retrieving revision 1.46
retrieving revision 1.47
diff -C2 -d -r1.46 -r1.47
*** plugin.h	24 Apr 2004 06:51:28 -0000	1.46
--- plugin.h	5 May 2004 08:01:30 -0000	1.47
***************
*** 110,127 ****
  typedef struct stats_s stats_t;
  
  struct stats_s
  {
      unsigned int packets_sent;
      unsigned int packets_recvd;
      unsigned short ttl;
!     double rtt_min, rtt_max, rtt_avg;
  };
  
  struct error_ptrs
  {
  	void (*err_ret) (const char *fmt, ...);
  	void (*err_sys) (const char *fmt, ...);
  	void (*err_dump) (const char *fmt, ...);
  	void (*err_msg) (const char *fmt, ...);
  	void (*err_quit) (const char *fmt, ...);
  };
--- 110,150 ----
  typedef struct stats_s stats_t;
  
+ /*! \struct stats_s
+ 	\brief Statistics structure
+ 	
+ 	This structure holds the statistics per target
+ */
  struct stats_s
  {
+ 	//! Number of packets sent
      unsigned int packets_sent;
+ 	//! Number of packets received
      unsigned int packets_recvd;
+ 	//! last time to live received
      unsigned short ttl;
! 	//! least round trip time
!     double rtt_min, 
! 	//! max round trip time
! 		rtt_max, 
! 	//! average round trip time
! 		rtt_avg;
  };
  
+ /*! \struct error_ptrs
+ 	\brief Error Function Pointers
+ 	
+ 	This structure holds pointers to various error functions
+ */
  struct error_ptrs
  {
+ 	//! Print a nonfatal error related to a system call
  	void (*err_ret) (const char *fmt, ...);
+ 	//! Print a fatal error related to a system call and exit
  	void (*err_sys) (const char *fmt, ...);
+ 	//! Print a fatal error related to a system call, dump core, and exit
  	void (*err_dump) (const char *fmt, ...);
+ 	//! Print a nonfatal error unrelated to a system call.
  	void (*err_msg) (const char *fmt, ...);
+ 	//! Print a fatal error unrelated to a system call and exit
  	void (*err_quit) (const char *fmt, ...);
  };
***************
*** 129,305 ****
  typedef struct target_s target_t;
  
  struct target_s
  {
!     /// next target in list
      target_t *next;
!     /// user specified entry
      char *entry;
!     /// list of ports to scan
      int ports[MAX_PORTS];
!     /// address info, including family, protocol, and socket type
      struct addrinfo *addrinfo;
!     /// netmask
      unsigned int netmask;
!     /// extra hosts involved in this (ie, w/netmask)
      unsigned int extra_hosts;
!     /// broadcast address
      unsigned short broadcast;
!     /// number of ports in this host
      uint32_t num_ports;
!     /// statistics
      stats_t stats;
  };
  
! /** \struct pluginContext
!   * Contains useful plugin data
    */
  typedef struct sonar_options_s
  {
!     // / Delay after running this type of scan (advanced option)
      int iPostDelay;
!     // / Delay after each host
      int iHostDelay;
!     // / Timeout per host
      int iTimeout;
!     // / do we have broadcast addresses in the targets?
      int bBroadcast;
  
!     // / Verbosity level (0 to 5)
      int iVerbose;
!     // / Fork into daemon mode? (0/1)
      int bFork;
!     // / Command line
      char *sCommandLine;
!     // / Number of scanning cycles to run
      unsigned int iCount;
!     // / Random order of hosts?
      int bRandom;
  } sonar_options_t;
  
! /** \struct plugin_s
!   * Definition for the plugin interface
!   * This is return to sonar from the plugin_init function
    */
  typedef struct plugin_s
  {
!     // / unique ID assigned at run time
      uint32_t pluginID;
!     // / plugin api interface version, lower versions _may_ be supported
      uint8_t version;
!     // / plugin type (INPUT_PLUGIN | OUTPUT_PLUGIN for an I/O plugin)
      uint8_t type;
  
!     // / last error from this plugin
      int16_t *err;
!     // / ready to use flag, not modified by sonar
      uint8_t ready:4,
!         // / The plugin was selected
        selected:4;
  
!     // / Plugin character (ie, -sI, -sA, -sL, -oL)
      char plugin_char;
!     // / Short name (ie, "icmp scan", "log file output")
      char *shortname;
!     // / Long name (ie, "ICMP Scanning Plugin: requires root...")
      char *longname;
  
!     // / Initialize this plugin
      void *(*plugin_init) (void *in_data);
!     // / Destroy this plugin
      int (*plugin_destroy) (void);
  
!     // / Open the input/output/network source
      int (*plugin_open) (void *c_data, int i_data);
!     // / Close the input/output/network source
      int (*plugin_close) (void);
!     // / Get next host, returned in hostname, only for input plugins
!     // / Set next host, for network plugins
      int (*plugin_next) (char *hostname);
  
!     // / Do the sweep (network plugins)
      int (*plugin_sweep) (target_t * targets);
  
!     // / Output plugin's general message output function
      int (*plugin_output) (char *msg, va_list * ap);
!     // / output plugins result output function
      int (*plugin_results) (target_t * result, unsigned int num);
  
!     // / prints, via sonar_t->output(), line(s) to add to sonar_usage()
      void (*plugin_usage) (void);
!     // / prints, via sonar_t->output(), line(s) to add to the status report
      void (*plugin_status) (void);
  
!     // / Return the last error
      int (*plugin_last_error) (void);
  
  } plugin_t;
  
! /** \struct sonar_s
!   * Definition for the plugin interface
!   * This is passed to the plugin, via plugin_init, from sonar with useful
!   * function pointers and information, such as what version
!   * of sonar is loading the plugins, and pointers to sonar_msg(char *,...), etc.
!   */
  typedef struct sonar_s
  {
!     // / Major version number
      uint8_t ver_major,
!         // / Minor version number
        ver_minor,
!         // / Revision number
        revision,
!         // / Plugin API version 1.X (so for 1.4, set this to 4)
        api;
  
!     // / Pointer to a memory copier from sonar (XXX: remove)
      void (*memput) (char **dest, const char *src, const int len);
  
!     // / Pointer to the Messsage output (ie, with a timestamp) function from
!     // sonar
      void (*message) (char *msg, ...);
  
!     // / let the resolving function live in sonar, so each network plugin
!     // wont have to write its own
!     // / unless it wants to
      struct addrinfo *(*resolve) (const char *host, const char *serv,
                                   int family, int socktype);
!     // / Pointer to sonar's output to console function (no timestamp)
      int (*output) (char *msg, ...);
  
!     // / Pointer to usage function, for error reports
      void (*usage) (const char *);
  
!     // / Pointer to a function to get root priveleges
      int (*getprivs) (void);
!     // / Pointer to a function to drop root priveleges
      int (*dropprivs) (uid_t);
!     // / find a target, for updating
      target_t *(*find_target) (struct sonar_s * this, struct addrinfo * ai);
  
!     // / Name of file we are (for permissions checking)
      char *my_name;
  
!     // struct for error function pointers
      struct error_ptrs *err_ptrs;
  
!     // / list of attack vectors
      target_t *vectors;
!     // / number of targets
      unsigned int num_targets;
!     // / number of ports
      unsigned int num_ports;
  
!     // / Useful global options
      sonar_options_t opts;
  } sonar_t;
  
! /** \struct plugin_list_s
!   * Wrapper for plugin_t to be used as an array
!   */
  typedef struct plugin_list_s
  {
!     // / Pointer to a plugin_t structure
      plugin_t *plug;
!     // / Handle to library opened with \c lt_dlopen(3)
      void *handle;
  } plugin_list_t;
--- 152,346 ----
  typedef struct target_s target_t;
  
+ /*! \struct target_s
+ 	\brief Target specification
+ 	
+ 	This structure is filled in with various information about the targets
+ 	This structure will be used in a linked list. Targets are filled in
+ 	by calling sonar_add_target with the user's target specification
+ */
  struct target_s
  {
!     //! Link to the next target in list
      target_t *next;
!     //! Contains only the hostname (no ports or netmasks)
      char *entry;
!     //! List of ports to scan (see PORT_SCAN et al. in plugin.h)
      int ports[MAX_PORTS];
!     //! Address info structue, including family, protocol, and socket type (see getaddrinfo(3))
      struct addrinfo *addrinfo;
!     //! Netmask (0-32)
      unsigned int netmask;
!     //! Number of extra hosts involved in this target (ie, w/netmask)
      unsigned int extra_hosts;
!     //! Set if this target is a broadcast address
      unsigned short broadcast;
!     //! Number of ports in this host
      uint32_t num_ports;
!     //! Statistics structure
      stats_t stats;
  };
  
! /*! \struct sonar_options_s
! 	\brief Contains useful plugin data
! 	
! 	This structure contains all the various global options for plugin(s)
    */
  typedef struct sonar_options_s
  {
!     //! Delay after running this type of scan (advanced option)
      int iPostDelay;
!     //! Delay after each host
      int iHostDelay;
!     //! Timeout per host
      int iTimeout;
!     //! do we have broadcast addresses in the targets?
      int bBroadcast;
  
!     //! Verbosity level (0 to 5)
      int iVerbose;
!     //! Fork into daemon mode? (0/1)
      int bFork;
!     //! Command line
      char *sCommandLine;
!     //! Number of scanning cycles to run
      unsigned int iCount;
!     //! Random order of hosts?
      int bRandom;
  } sonar_options_t;
  
! /*! \struct plugin_s
! 	\brief Definition for the plugin interface
! 	
! 	Your plugin(s) should return a filled in structure from the plugin_init function.  
! 	Sonar will expect all the applicable function pointers to be valid.
    */
  typedef struct plugin_s
  {
!     //! unique ID assigned at run time by sonar
      uint32_t pluginID;
!     //! plugin api interface version requested, lower versions _may_ be supported
      uint8_t version;
!     //! plugin type (INPUT_PLUGIN | OUTPUT_PLUGIN for an I/O plugin)
      uint8_t type;
  
!     //! last error from this plugin
      int16_t *err;
!     //! ready to use flag, not modified by sonar
      uint8_t ready:4,
!     //! The plugin was selected
        selected:4;
  
!     //! Plugin character (ie, -sI, -sA, -sL, -oL)
      char plugin_char;
!     //! Short name (ie, "icmp scan", "log file output")
      char *shortname;
!     //! Long name (ie, "ICMP Scanning Plugin: requires root...")
      char *longname;
  
!     /*! \fn plugin_init (void *in_data)
! 		\brief Initialize this plugin
! 		
! 		Return a pointer to a filled in plugin_s structure
! 	*/
      void *(*plugin_init) (void *in_data);
!     //! Destroy this plugin
      int (*plugin_destroy) (void);
  
!     /*! \fn plugin_open (void *c_data, int i_data)
! 		\brief Open the input/output/network source
! 		
! 		For input plugins, please return the size of the buffer you use.
! 		Everything else should return PLUGIN_OK on success and PLUGIN_ERROR
! 		on error.
! 	*/
      int (*plugin_open) (void *c_data, int i_data);
!     //! Close the input/output/network source
      int (*plugin_close) (void);
!     //! Get next host, returned in hostname, only for input plugins
      int (*plugin_next) (char *hostname);
  
!     //! Do the sweep (network plugins)
      int (*plugin_sweep) (target_t * targets);
  
!     //! Output plugin's general message output function
      int (*plugin_output) (char *msg, va_list * ap);
!     //! output plugins result output function
      int (*plugin_results) (target_t * result, unsigned int num);
  
!     //! prints, via sonar_t->output(), line(s) to add to sonar_usage()
      void (*plugin_usage) (void);
!     //! prints, via sonar_t->output(), line(s) to add to the status report
      void (*plugin_status) (void);
  
!     //! Return the last error
      int (*plugin_last_error) (void);
  
  } plugin_t;
  
! /*! \struct sonar_s
! 	\brief Definition for the plugin interface
! 
! 	This is passed to the plugin, via plugin_init, from sonar with useful
!   	function pointers and information, such as what version
!   	of sonar is loading the plugins, and pointers to sonar_msg(char *,...), etc.
!  */
  typedef struct sonar_s
  {
!     //! Major version number
      uint8_t ver_major,
!     //! Minor version number
        ver_minor,
!     //! Revision number
        revision,
! 	//! Plugin API version 1.X (so for 1.4, set this to 4)
        api;
  
!     //! Pointer to a memory copier from sonar (XXX: remove)
      void (*memput) (char **dest, const char *src, const int len);
  
!     //! Pointer to the Messsage output (ie, with a timestamp) function
      void (*message) (char *msg, ...);
  
!     //! Resolve a hostname, usually called with the last 3 arguments NULL, and 0
      struct addrinfo *(*resolve) (const char *host, const char *serv,
                                   int family, int socktype);
!     //! Pointer to sonar's output to console function (no timestamp)
      int (*output) (char *msg, ...);
  
!     //! Pointer to usage function, for error reports
      void (*usage) (const char *);
  
!     //! Pointer to a function to get root priveleges
      int (*getprivs) (void);
!     //! Pointer to a function to drop root priveleges
      int (*dropprivs) (uid_t);
!     //! find a target, for updating
      target_t *(*find_target) (struct sonar_s * this, struct addrinfo * ai);
  
!     //! Name of file we are (for permissions checking)
      char *my_name;
  
!     //! struct for error function pointers
      struct error_ptrs *err_ptrs;
  
!     //! list of attack vectors
      target_t *vectors;
!     //! number of targets
      unsigned int num_targets;
!     //! number of ports
      unsigned int num_ports;
  
!     //! Useful global options
      sonar_options_t opts;
  } sonar_t;
  
! /*! \struct plugin_list_s
! 	\brief Wrapper for plugin_t to be used as an array
! */
  typedef struct plugin_list_s
  {
!     //! Pointer to a plugin_t structure
      plugin_t *plug;
!     //! Handle to library opened with \c lt_dlopen(3)
      void *handle;
  } plugin_list_t;