View
66
Download
0
Category
Preview:
Citation preview
Logging Configuration
The following describes how to enable audit and event logging on the controller.
• Logging Configuration Overview, page 1
Logging Configuration OverviewThe Learning Network License system enables audit, event, and general logging by default on the controller.It also automatically enables Smart Licensing logging after you register your controller with Smart Licensing.See the following table for descriptions and default file output locations.
Table 1: Controller Logging Descriptions and Default Output Locations
Default Output LocationsDescriptionLog Type
~/SCA/logs/sca.log
console (ERROR severity andabove)
system transactionsaudit logging
/var/log/user.log
~/SCA/logs/sca.log
console (ERROR severity andabove)
events the system generates,tracking:
• agents connecting to ordisconnecting from thecontroller
• anomaly events (INFOseverity)
• updated anomaly eventswhere the severity increases
event logging
~/SCA/logs/sca.log
console (ERROR severity andabove)
general system informationgeneral logging
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 1
Default Output LocationsDescriptionLog Type
/var/log/user.log
~/SCA/services/sa-server/sa-server.log
Smart Licensing transactions,including when you register thecontroller, and when you use agentlicense entitlements
Smart Licensing logging
~/SCA/services/pxgrid/pxg.loglogging related to pxGridintegration with ISE
pxGrid logging
The agent logs general system information to multiple log files, located on the agent at ~/DLA/LOG.
The Controller Logging Configuration FileThe controller uses the logback logging framework to log information, including anomaly events,agent/controller connection and disconnection events, audit logging, general system logging, and SmartLicensing logging. Cisco provides a sample configuration file on the controller at ~/SCA/sample_logback.xml.This file provides an example of logging configuration syntax. If you copy this file and rename it tosca-logback.xml, you can update the logging configuration settings.
If you incorrectly configure sca-logback.xml due to invalid or malformed XML syntax, the system logsan error message to the console, but does not start logging. If you incorrectly configure sca-logback.xmldue to unrecognized nodes, options, or class names, the system logs an error message to the console. Itthen loads the remaining valid configuration in the file, and otherwise loads default logging settings.
Note
Beneath the parent configuration node are the following:
• logger - the class that provides the level of log messages
• root - the root logger class
• appender - the class that output the log message
By default, the root logger is configured to log INFO messages to the console and the ~/SCA/logs/sca.loglog file. However, note that the console appender is configured to log ERROR and above by default, so INFOmessages are not displayed on the console.
The com.cisco.sln.utils.log.ScaCefLogger logger does not have a logging level configured, but inheritslogging INFO messages. By default, this logger logs the CEF messages, which are INFO level, to the/var/log/user.log log file, ~/SCA/logs/sca.log log file, and the console.
For more information on logback, see http://logback.qos.ch/documentation.html.
syslog Export to External HostsWithin the sample_logback.xml configuration file, the ScaCefLogger logger controls logging anomaly CEFevents to syslog. You can modify this configuration to change the host that receives these events.
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.12
Logging ConfigurationThe Controller Logging Configuration File
sca-logback.xml Creation
To update the logging configuration, first copy the sample_logback.xml file and rename it to sca-logback.xml,then open it and view the markup.
General Configuration
By default, the system checks sca-logback.xml for changes every minute. If it detects changes, the systemupdates the logging configuration. To disable this check, set the scan attribute equal to false.
If you set the scan attribute equal to false, you must restart the controller's processes before the systemupdates logging configuration.
Note
The following default configuration root element configuration controls this setting.<configuration scan="true"></configuration>If you want to change the sca-logback.xml check frequency, add the scanPeriod attribute to theconfiguration element, and set it equal to a number of seconds, minutes, hours, or days. The followingprovides an example.<configuration scan="true" scanPeriod="10 seconds"></configuration>
ScaCefLogger Logger Configuration
The following is the ScaCefLogger default configuration.<logger name="com.cisco.sln.utils.log.ScaCefLogger">
<appender-ref ref="SYSLOG" /></logger>
If you need to change logging level, add a level attribute to the ScaCefLogger logger element. The followingprovides an example.
<logger name="com.cisco.sln.utils.log.ScaCefLogger" level="TRACE"><appender-ref ref="SYSLOG" />
</logger>If you need to stop logging, add level="OFF" as an attribute to the ScaCefLogger logger element. The followingprovides an example.
<logger name="com.cisco.sln.utils.log.ScaCefLogger" level="OFF"><appender-ref ref="SYSLOG" />
</logger>
The system logs anomaly event CEF messages with an INFO logging level. The ScaCefLogger loggerinherits INFO logging level from the parent root logger. If you change the ScaCefLogger logging level,select a level that contains INFOmessages (TRACE, DEBUG, INFO). If you override this with a level that doesnot include INFO messages (WARN, ERROR), the system cannot write anomaly event messages to syslog.
Note
The appender-ref element references the SYSLOG appender which controls the host that receives these anomalyevents.
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 3
Logging ConfigurationThe Controller Logging Configuration File
SYSLOG Appender Configuration
The SYSLOG appender, by default, logs to the syslog on the local host. The following is the default SYSLOGappender configuration.
<appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender"><syslogHost>localhost</syslogHost><facility>USER</facility><suffixPattern>%msg</suffixPattern>
</appender>The syslogHost element controls the target for the logged anomaly events. Update this to the hostname ofyour external host or SIEM to export syslog to that host.
The facility element controls the syslog facility. LOCAL0 through LOCAL7 are unused facilities you can definefor custom purposes.
Because the USER facility generates the events, Cisco recommends you keep this setting.Note
The suffixPattern element controls the format of the non-standard message component. See http://logback.qos.ch/manual/layouts.html for the discussion of PatternLayout and more information on how toconfigure suffixPattern.
To define a port on the host other than the default port 514, you can add the port element as a child of theappender element and define a different port in that element's text. The following provides an example.
<appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender"><syslogHost>externalHostName</syslogHost><port>515</port><facility>USER</facility><suffixPattern>%msg</suffixPattern>
</appender>
Changes Saved
Save your changes to the file. The system updates the logging configuration the next time it checks the file.
Log File Location
The system by default outputs the anomaly events to /var/log/user.log.
Updating a syslog Target Host
Before You Begin
• Log into the controller VM console.
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.14
Logging ConfigurationThe Controller Logging Configuration File
SUMMARY STEPS
1. cd ~/SCA
2. cp sample_logback.xml sca-logback.xml
3. vi sca-logback.xml
4. If you want to change the logging level, add level="TRACE" or level="DEBUG" as an attribute to theScaCefLogger logger element, or level="OFF" as an attribute to the ScaCeflogger logger element todisable anomaly event logging.
5. If you want to define a port for the syslog host other than the default port 514, add a port element as achild of the SYSLOG appender element, then add the port number as the port element text.
6. Press Esc, then enter :wq!, then press Enter.
DETAILED STEPS
PurposeCommand or Action
Change to the ~/SCA directory.cd ~/SCA
Example:
Step 1
user@host:~$ cd ~/SCA
Make a copy of the sample_logback.xmlconfiguration file, and name itsca-logback.xml.
cp sample_logback.xml sca-logback.xml
Example:user@host:~/SCA$ cp sample_logback.xml sca-logback.xml
Step 2
Open the sca-logback.xml configurationfile in vi.
vi sca-logback.xml
Example:
Step 3
user@host:~/SCA$ vi sca-logback.xml
Change the logging level, or disable it.If you want to change the logging level, add level="TRACE" orlevel="DEBUG" as an attribute to the ScaCefLogger logger element, or
Step 4
level="OFF" as an attribute to the ScaCeflogger logger element todisable anomaly event logging.
Example:<logger name="com.cisco.sln.utils.log.ScaCefLogger"
level="TRACE">
Update the target syslog host port.If you want to define a port for the syslog host other than the defaultport 514, add a port element as a child of the SYSLOG appender element,then add the port number as the port element text.
Step 5
Example:<port>515</port>
Save your changes and close the file.Press Esc, then enter :wq!, then press Enter.
Example:
Step 6
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 5
Logging ConfigurationThe Controller Logging Configuration File
PurposeCommand or Action
:wq!
What to Do Next
• View ~/SCA/logs/console.log to verify that the controller updated the logging configuration.
• View the logs to see syslog messages. The log destination depends on the facility you defined in theSyslogAppender appender. By default, the USER facility logs to /var/log/user.log.
Logging TimestampsBy default, sca.log and console.log use Coordinated Universal Time (UTC) timestamps.
In contrast, pxg.log, saserver.log, and sca_monitor.log use timestamps based on your current localtimezone. You can edit the logging properties files and run sed to update those logs to use UTC timestamps.
Updating Logging Configuration Files for UTC TimestampsUpdate the log4j.properties files to update timestamps from your local configured timezone to UTCtimezones. Find the following lines:
log4j.appender.file.layout=org.apache.log4j.PatternLayoutlog4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L -
%m%n
And update the lines to add the bold text:log4j.appender.file.layout=org.apache.log4j.EnhancedPatternLayoutlog4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss}{UTC} %-5p %c{1}:%L
- %m%n
Before You Begin
• Log into the controller VM console.
SUMMARY STEPS
1. cd ~/SCA/services/pxgrid
2. sudo vi log4j.properties, then enter your password when prompted3. Update the lines listed above.4. Press Esc, then enter :wq!.5. cd ~/SCA/services/sa-server
6. sudo vi log4j.properties, then enter your password when prompted7. Update the lines listed above.8. Press Esc, then enter :wq!.
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.16
Logging ConfigurationLogging Timestamps
DETAILED STEPS
PurposeCommand or Action
Change to the ~/SCA/services/pxgriddirectory.
cd ~/SCA/services/pxgrid
Example:user@host:~$ cd ~/SCA/services/pxgrid
Step 1
Open log4j.properties in the vi texteditor as a superuser.
sudo vi log4j.properties, then enter your password when prompted
Example:user@host:~/SCA/services/pxgrid$ sudo vi log4j.properties
Step 2
Update the log4j.properties file touse UTC timestamps.
Update the lines listed above.
Example:
log4j.appender.file.layout=org.apache.log4j.EnhancedPatternLayout
Step 3
log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-ddHH:mm:ss}{UTC} %-5p %c{1}:%L - %m%n
Save your changes, then exit the vi texteditor.
Press Esc, then enter :wq!.Step 4
Change to the~/SCA/services/sa-server directory.
cd ~/SCA/services/sa-server
Example:user@host:~$ cd ~/SCA/services/sa-server
Step 5
Open log4j.properties in the vi texteditor as a superuser.
sudo vi log4j.properties, then enter your password when prompted
Example:user@host:~/SCA/services/sa-server$ sudo vi log4j.properties
Step 6
Update the log4j.properties file touse UTC timestamps.
Update the lines listed above.
Example:
log4j.appender.file.layout=org.apache.log4j.EnhancedPatternLayout
Step 7
log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-ddHH:mm:ss}{UTC} %-5p %c{1}:%L - %m%n
Save your changes, then exit the vi texteditor.
Press Esc, then enter :wq!.Step 8
Updating UTC Timestamps for the Controller Monitor LogsRun sed to display UTC timestamps in the sca_monitor.log log file.
Before You Begin
• Log into the controller VM console.
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 7
Logging ConfigurationLogging Timestamps
DETAILED STEPS
PurposeCommand or Action
Run sed to update how the sca_monitor.log logfile displays timestamps.
sed -ie 's/(date /(date --utc /' SCA/sca_monitor.sh
Example:user@host:~$ sed -ie 's/(date /(date --utc /'SCA/sca_monitor.sh
Step 1
Accessing Audit and Event Log Files
Before You Begin
• Log into the controller VM console on the ESXi hypervisor.
SUMMARY STEPS
1. cd ~/var/log
2. vi syslog or vi user.log
DETAILED STEPS
PurposeCommand or Action
Change to the /var/log directory.cd ~/var/log
Example:
Step 1
user@host:~$ cd ~/var/log
Edit the syslog or user.log log file.vi syslog or vi user.log
Example:
Step 2
user@host:~/var/log$ vi syslog
Example:user@host:~/var/log$ vi user.log
Audit Log FieldsFor Version 1.0, the system logs each audit log message in the following format:
userId [timestamp] category > {jsonData}
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.18
Logging ConfigurationAccessing Audit and Event Log Files
Table 2: Audit Log Version 1.0 Field Descriptions
DescriptionField
ID of the user associated with the transactionuserId
Date and time the transaction occurredtimestamp
The type of transactioncategory
Information associated with the transaction typejsonData
For Version 1.1 and greater, the system logs each audit log message in the following format:
[timestamp] - User(userInfo) - source: category > {jsonData}
Table 3: Audit Log Version 1.1 and Greater Field Descriptions
DescriptionField
ISO8061 timestamp when the transaction occurredtimestamp
One of the following values related to users:
• unknown - an unknown user
• id - a user's ID (username unknown)
• id, username - a user's ID and username
userInfo
the source that generated the audit log message:
• authentication - user authentication duringlogin, user logout, and user account passwordchange
• configuration - configuration applied to anagent by the controller
• dla - agent configuration, such as enable,disable, and certificate pinning
• download - PCAP file download
• mitigation - mitigation creation, deletion, andreversion
• pbc - PCAP file download requests
• user - user account creation, update, andconversion to an API user
• whitelisting - whitelist rule creation anddeletion
source
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 9
Logging ConfigurationAccessing Audit and Event Log Files
DescriptionField
the type of transaction task requested by the user, andthe success or failure, depending on the source
category
information associated with the transaction type,depending on the source
jsonData
Event Log Fields
Table 4: Event Log Field Descriptions
DescriptionField
The date and time the system detected the event.timestamp
The host that logged the message.host
The CEF version, always 0.version
The associated vendor, always Cisco.deviceVendor
The associated vendor product, always SLN.deviceProduct
The controller version.deviceVersion
The event type:
• SLN_ANOMALY for anomaly events
• SLN_DLA for agent health status events
signatureID
Description of the event log message.name
Integer representing the event severity:
• 0 for low
• 5 for medium
• 10 for high
severity
Information related to the anomaly event. If this is anagent health status event, this contains no data.
extension
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.110
Logging ConfigurationAccessing Audit and Event Log Files
Event Log Message Examples
The system logs each event log message in CEF. When the system adds an event log message to the syslog,it prepends a timestamp and host, in the following format:timestamp host CEF:version|deviceVendor|deviceProduct|deviceVersion|signatureID|name|severity|extension
The following describes a connection between agent and controller has gone down:Jan 1 00:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_DLA|CON_DOWN|0|deviceExternalId=1
The following describes an agent in safe mode:Jan 1 21:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_DLA|DLA is in safe mode|0|
The following describes an updated agent configuration:Jan 1 11:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_DLA_INTERFACES|Interfaces have changed on dla 2|5|
The following describes a user asking for more anomalies:Jan 1 21:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_MORE_LESS|User admin asked for more anomalies|0|
The following describes a sample anomaly:Jan 1 22:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_ANOMALY|Small total number of bytes (10.00 bytes)from an external mixed host in Chile (RM) 200.10.9.23 in Chile (anomalous trafficenters and exits the branch)|10|deviceExternalId=1 dst=192.0.2.14 dvchost=samplenameexternalId=1923 startTime=2016-01-01T22:08:00Z
Smart Licensing Log FieldsThe system logs each Smart Licensing log message in the following format:
timestamp hostname userId: %CISCO-SMART-LIC% message
Table 5: Smart Licensing Log Field Descriptions
DescriptionField
Date and time the transaction occurredtimestamp
Name of the host where the transaction occurredhostname
ID of the user associated with the transactionuserId
The log messagemessage
Accessing Controller General Log Files
Before You Begin
• Log into the controller VM console on the ESXi hypervisor.
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 11
Logging ConfigurationAccessing Controller General Log Files
SUMMARY STEPS
1. cd ~/SCA
2. vi SCA.log
DETAILED STEPS
PurposeCommand or Action
Change to the /SCA directory.cd ~/SCA
Example:
Step 1
user@host:~$ cd ~/SCA
Edit the SCA.log general controller log file.vi SCA.log
Example:
Step 2
user@host:~/SCA$ vi SCA.log
Accessing Agent Log Files
Before You Begin
• For an agent deployed to a UCS E-Series blade server, log into the agent VM console on the ESXihypervisor. For an agent deployed as a virtual service, log into the virtual service console, then exit theinitial menu to access the administrator settings.
SUMMARY STEPS
1. 1) File access
2. 1) Log files
3. 1) List log files
4. 2) View log file
5. Enter a log file name. You can use the asterisk character (*) as a wild card.6. :qto exit
DETAILED STEPS
PurposeCommand or Action
Access the File access menu options.1) File access
Example:
Step 1
Enter a number: 1
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.112
Logging ConfigurationAccessing Agent Log Files
PurposeCommand or Action
Access the log files options.1) Log files
Example:
Step 2
Enter a number: 1
List the available agent log files.1) List log files
Example:
Step 3
Enter a number: 1
View log files.2) View log file
Example:
Step 4
Enter a number: 2
Select a log file to view.Enter a log file name. You can use the asterisk character (*) asa wild card.
Step 5
Example:Enter filename, or a pattern for a menu of files:
log-name
Exit viewing the log file.:qto exit
Example:
Step 6
:q
Exporting Agent Troubleshooting FilesYou can export your agent troubleshooting files to an external host. Do this when directed by Cisco Support.
Before You Begin
• For an agent deployed to a UCS E-Series blade server, log into the agent VM console on the ESXihypervisor. For an agent deployed as a virtual service, log into the virtual service console, then exit theinitial menu to access the administrator settings.
SUMMARY STEPS
1. 1) File access
2. 5) ML debug files
3. 1) List ML debug files
4. 2) Send ML debug files to remote system, then ip-address, then username, then press Enter, thenpassword
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 13
Logging ConfigurationExporting Agent Troubleshooting Files
DETAILED STEPS
PurposeCommand or Action
Access the File access menu options.1) File access
Example:
Step 1
Enter a number: 1
Access the log files options.5) ML debug files
Example:
Step 2
Enter a number: 5
List the available debugging files.1) List ML debug files
Example:
Step 3
Enter a number: 1
Export the debugging files to a remotesystem.
2) Send ML debug files to remote system, then ip-address, thenusername, then press Enter, then password
Example:Enter a number: 2Name or address of remote host []? 192.168.0.1
Step 4
Destination username []? adminThe destination filename path can absolute, or relativeto home dir.Destination filename [scala.out]:admin@remotehost's password: <password>
Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.114
Logging ConfigurationExporting Agent Troubleshooting Files
Recommended