Editing Example Cartographer Agent Configuration


__TOC__ 

== What are the configuration files? ==

Cartographer agents are configured using several configuration files, all in XML format.

The configuration files are:
* xmpd.xml - Agent engine configuration settings
* cartographer.pem - Agent certificate authority keys
* appdata.xml - Cartographer plugin data file storing application data
* connectiondata.xml - Cartographer plugin data file storing connection data
* cartographer.xml - Cartographer plugin configuration settings
* cartographer-local.xml - Local, system-specific Cartographer-plugin configuration directives

== Validating your configuration Files ==

An XML schema file defining Cartographer agent configuration files can be found [http://xmlns.krupczak.org/xsd/xmpdconfigs-1.0.xsd here].  To check the correctness of your config files, we suggest you use the [http://xmlsoft.org/xmllint.html xmllint] utility included in the [http://www.xmlsoft.org/index.html libxml2] software distribution.

<pre>
% xmllint --noout --schema http://xmlns.krupczak.org/xsd/xmpdconfigs-1.0.xsd your-config.xml
</pre>

== xmpd.xml ==

Here is a basic ''xmpd.xml'' file that comes with the agent install.

<pre>
<?xml version="1.0"?>

<xmpd_config version="2" 
   xmlns="http://xmlns.krupczak.org/xsd/xmpdconfigs-1.0">

<xmpd_trace>0</xmpd_trace>
<xmpd_verbose>0</xmpd_verbose>
<xmpd_daemon>0</xmpd_daemon>
<xmpd_eventageoutinterval>300</xmpd_eventageoutinterval>
<xmpd_defaultmanager>system</xmpd_defaultmanager>
<xmpd_autoupgrade>true</xmpd_autoupgrade>

<xmpd_authenuser>
<user>changeit</user>
<protocol_ops>all</protocol_ops>
<mibs>cartographer,mib2,core</mibs>
</xmpd_authenuser>

<xmpd_authenuser>
<user>public</user>
<protocol_ops>Response GetRequest SelectTableRequest Trap Information</protocol_ops>
<mibs>all</mibs>
</xmpd_authenuser>

</xmpd_config>
</pre>

== cartographer.xml ==

Here is a basic ''cartographer.xml'' that is included in the Cartographer agent distribution.

<pre>
<?xml version="1.0"?>

<cartographerConfig version="4"
   xmlns="http://xmlns.krupczak.org/xsd/xmpdconfigs-1.0">

<dependencyAgeOutInterval>600</dependencyAgeOutInterval>

<peerAgeOutInterval>1800</peerAgeOutInterval>

<dependencyScanInterval>120</dependencyScanInterval>

<xmpAuthenUser>changeit</xmpAuthenUser>

</cartographerConfig>
</pre>

The configuration file version is 4.  This number should be monotonically increasing.  Cartographer agents will distribute and update this file amongst each other.  To deploy a new configuration file, simply edit a new one and place in the Cartographer home directory (e.g. ''/opt/cartographer'' or ''c:\program files\cartographer'').  The cartographer agent and plugins will periodically stat their config files and re-read them if they have changed and if the version number is greater than the one they previously read and parsed.

The ''<dependencyAgeOutInterval>'' XML element tells Cartographer how long dependencies should remain in its tables, before pruning, if it has not been re-discovered or re-validated.

The ''<peerAgeOutInterval>'' XML element tells Cartographer how long a peer agent should remain in its peer table, before pruning, if it has not been re-discovered or re-validated.

The ''<dependencyScanInterval>'' XML element tells Cartographer how often, in seconds, to wait before searching for dependencies.  120 means to wait two minutes before scanning for dependencies again.  This number represents a tradeoff between CPU utilization and dependency discovery granularity.  The smaller the number, the more often dependencies are searched for but the more CPU the agent consumes.

The ''<xmpAuthenUser>'' XML elements tells the Cartographer agent which XMP authenticated user to use when communicating with other XMP agents.  This value should be specified in the ''xmpd.xml'' configuration file with appropriate permissions.  The Cartographer plugin needs ''GetRequest'', ''SelectTableRequest'', ''Trap'', and ''Information'' protocol operations permission for the ''cartographer'', ''mib2'', and ''core'' MIBs.

== cartographer-local.xml ==

* ''<cartographerLocal version="1"> </cartographerLocal>'' XML element identifies the configuration file and its version.  Agents distribute and read newer versions.  Version numbers should be monotonically increasing integers.

* The ''<system name="hostname"> </system>'' XML element delimits configuration directives for the specified system.  You can place multiple system elements in the cartographer-local.xml configuration file.  Hostname can be a FQDN or partial.

* ''<dependency> </dependency>'' XML element can be used to add static dependencies via this configuration directive.  This directive is helpful if you have a known dependency that Cartographer is not able to discover.  Configuring dependencies this way ensures that they included in Cartographer's intelligence algorithms.

* ''<logfileDependency> </logfileDependency>'' XML element can be used to discover dependencies by scanning logfiles using regular expressions and adding dependencies when matches occur.

* ''<logfileMonitor> </logfileMonitor>'' XML element can be used to scan logfiles for regular expressions and send XMP events when matches occur.

Here is an example ''cartographer-local.xml'' configuration file.

<pre>
<?xml version="1.0"?>

<cartographerLocal version="20"
   xmlns="http://xmlns.krupczak.org/xsd/xmpdconfigs-1.0">

<system name="vmguest">
  <dependency>
    <dependClient>127.0.0.1</dependClient>
    <dependServer>vmhost</dependServer>
    <dependType>dependVM</dependType>
    <dependArgs></dependArgs>
    <dependReference>dependOutbound</dependReference>
  </dependency>
</system>

<system name="emailServer">
  <logfileDependency>
   <logfile>/var/log/maillog</logfile>
     <dependType>dependEmail</dependType>
     <addExpression>imap-login.*user=(.*),.*rip=(.*), lip</addExpression>
     <removeExpression></removeExpression>
     <dependClient>$2</dependClient>
     <dependServer>emailServer</dependServer>
     <dependArgs>user='$1'</dependArgs>
     <scanInterval>120</scanInterval>
     <timeout>3600</timeout>
  </logfileDependency>
</system>

</pre>

== appdata.xml ==

== connectiondata.xml ==

== Example Directives ==

=== Database Connections ===

Assuming that mySQL and PostgreSQL are properly configured for sysloging, these entries will scan syslog files for database connections and create dependencies for the corresponding clients.  Cartographer agents will also scan for database connections via the TCP connection table, however, Cartographer agents may miss very short lived TCP connections.
 
<pre>
<logfileDependency>
  <logfile>/var/log/mysqld.log</logfile>
  <dependType>dependDB</dependType>
  <addExpression>Connect *(.*)@(.*) on</addExpression>
  <removeExpression></removeExpression>
  <dependClient>$2</dependClient>
  <dependServer>mankato</dependServer>
  <dependArgs>application='mysqld' user='$1'</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>3600</timeout>
</logfileDependency>

<logfileDependency>
  <logfile>/var/log/messages</logfile>
  <dependType>dependDB</dependType>
  <addExpression>postgres.*connection received: host=(.*) </addExpression>
  <removeExpression></removeExpression>
  <dependClient>$1</dependClient>
  <dependServer>onms</dependServer>
  <dependArgs>application='postgres'</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>3600</timeout>
</logfileDependency>
</pre>

=== Search for DHCP Clients ===

The ISC DHCP daemon logs clients that it assigns addresses to.  Snarfing these log entries allows Cartographer to determine DHCP clients.

<pre>
<logfileDependency>
  <logfile>/var/log/messages</logfile>
  <dependType>dependDHCP</dependType>
  <addExpression>DHCPACK on (.*) to (.*) via (.*)</addExpression>
  <removeExpression></removeExpression>
  <dependClient>$1</dependClient>
  <dependServer>127.0.0.1</dependServer>
  <dependArgs>interface='$3' macaddr='$2'</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>3600</timeout>
</logfileDependency>
</pre>

=== Search for IMAP Email User Dependencies ===

<pre>
<logfileDependency>
  <logfile>/var/log/maillog</logfile>
  <dependType>dependEmail</dependType>
  <addExpression>imap-login.*user=(.*),.*rip=(.*), lip</addExpression>
  <removeExpression></removeExpression>
  <dependClient>$2</dependClient>
  <dependServer>uncasville</dependServer>
  <dependArgs>user='$1'</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>3600</timeout>
</logfileDependency>
</pre>

=== Search for VPN Dependencies ===

<pre>
<logfileDependency>
  <logfile>/var/log/messages</logfile>
  <dependType>dependVPN</dependType>
  <addExpression>openvpn.*Peer Connection.*with (.*):(.*)</addExpression>
  <removeExpression></removeExpression>
  <dependClient>$1</dependClient>
  <dependServer>127.0.0.1</dependServer>
  <dependArgs>VPN</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>21600</timeout>
</logfileDependency>
</pre>

=== Search for DNS Slave Servers Performing Zone Transfers ===

Slave client transferring from server:
<pre>
<logfileDependency>
  <logfile>/var/log/named.log</logfile>
  <dependType>dependDNS</dependType>
  <addExpression>.*transfer of.*from (.*)#</addExpression>
  <removeExpression></removeExpression>
  <dependClient>127.0.0.1</dependClient>
  <dependServer>$1</dependServer>
  <dependArgs>zone xfer</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>21600</timeout>
</logfileDependency>
</pre>

Server side log of client transfer will detect zone transfers to slaves:
<pre>
<logfileDependency>
  <logfile>/var/named/chroot/var/log/named.log</logfile>
  <dependType>dependDNS</dependType>
  <addExpression>client (.*)#.*transfer of (.*):.*</addExpression>
  <removeExpression></removeExpression>
  <dependClient>$1</dependClient>
  <dependServer>127.0.0.1</dependServer>
  <dependArgs>zone='$2' xfer</dependArgs>
  <scanInterval>120</scanInterval>
  <timeout>21600</timeout>
</logfileDependency>
</pre>

=== Logfile Monitor for Authentication Issues ===

Logins attempts on secure server machines may warrant additional scrutiny.

<pre>
<logfileMonitor>
  <logfile>/var/log/secure</logfile>
  <expression>Accepted password for .*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/secure</logfile>
  <expression>Failed password for .*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/maillog</logfile>
  <expression>postfix.*SASL LOGIN.*fail.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

</pre>

''saslauthd'' has been known to fall over at times and this makes users unhappy.

<pre>
<logfileMonitor>
  <logfile>/var/log/messages</logfile>
  <expression>.*kernel.*saslauthd.*seg.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>
</pre>

=== Virtual Machine Guest/Host Static Dependency ===

<pre>
 <dependency>
   <dependClient>127.0.0.1</dependClient>
   <dependServer>vmhost</dependServer>
   <dependType>dependVM</dependType>
   <dependArgs></dependArgs>
   <dependReference>dependOutbound</dependReference>
 </dependency>
</pre>

=== Security and Hacking Attempts ===

The Internet is full of despicable creatures out there attempting to break into our computers.  Here are a few logfile monitoring entries to alert us to the more interesting attack avenues.  Some of the expressions and logfiles are dependent on your local configuration.

<pre>
<logfileMonitor>
  <logfile>/var/log/httpd/ssl_error_log</logfile>
  <expression>phpMyAdmin.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/httpd/ssl_request_log</logfile>
  <expression>phpMyAdmin.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/httpd/access_log</logfile>
  <expression>phpMyAdmin.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/httpd/error_log</logfile>
  <expression>phpMyAdmin.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/maillog</logfile>
  <expression>Blocked.*SPAM.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/secure</logfile>
  <expression>Failed password for .*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/messages</logfile>
  <expression>Illegal DNS output.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>

<logfileMonitor>
  <logfile>/var/log/messages</logfile>
  <expression>Illegal SMTP output.*</expression>
  <scanInterval>120</scanInterval>
</logfileMonitor>
</pre>