1) Getting started - simplest testing

2) How it works - deeper insight

com.asw.MacAvast.MAD

This is the multi-threaded scanning daemon itself. This application does all the scanning, archive decompressing, decodes and handles the virus database, manages trial mode and checks licenses. The daemon is controlled via a textual, human-readable protocol, passed through an unix or ip tcp-style socket. Rouhly said, this binary itself is a full on-demand scanner with textual interface, able to serve more sessions in parallel, each of them under different license, able to upgrade to a new database even while scanning and capable of archive manipulations and infection cleaning where possible. From the command-line point of view, all the avast features are concetrated into this single binary, which might also serve as a service for a command-line based scanning tool or a remotely-driven scan scheduler.

avast!

This is a multi-threaded application which is responsible for all the higher GUI and user interaction. Also, this application launches the scanning daemon and loads the kernel extension. This application is also responsible for buffering and processing of all on-access events, caught in the kernel extension. There's also special agent which handles communication with the scanning daemon, in two independent sessions. And, also, this application performs the database update requests to get the fresh 400.vps file, when the daemon refuses to do the incremental update. You can drag and drop objects over the main scanning window and manipulate with files and archives. Virus chesting, encryption and reporting is done here as well.

avastKauth.kext

This is a kernel extension which catches after-close events on modified files, caches them and offers them in turn to the userspace agent. Note that the scan itself might be postponed, because we don't block the syscalls, and thus the contents won't be scanned immediately. This approach was chosen due to the OSX nature - the absolute majority of malware comes from outside world and isn't malicous for the OS X system itself. So, we decided to avoid the performance degradation and dependence-interlocking perils, typical for synchronous syscall-blocking on-access mechanisms, in behalf of untainted system behavior and maximum possible performance.

other components

This cathegory includes 400.vps (latest virus database file, included for users who can't upgrade immediately after installation), avast.scpt (script wrapper, intended for the mailer rule), simpleScanner (wrapping application for per-file on-demand scanning) and the rest of stuff.

1. useful defaults
   Some of the mentioned components can be user-tweaked using defaults from the domain com.avast.MacAvast. These defaults can be set using the command 'defaults write com.avast.MacAvast keyword value', and verified using 'defaults read com.avast.MacAvast [keyword]', see 'man defaults'. Issue these command as ordinary user who installed the Avast!. Such tweaking migh be very useful for various debugging activites, especially these particular keys:
   
   

   LogCompleteCommunication yes_or_no

   After enabling this feature (disabled by default), the application will start to log all communication with the daemon to the file 'BetaLog.txt', which is situated in '~/Library/Application Support/com.avast.MacAvast' directory.
   WARNING: This log tends to be very extensible and might grow to many megabytes in a while!

   MADLogRedirection log_file_path

   This default enables logging at the daemon's side to the specified file. This feature is off by default, but is useful for cases where the daemon crashes or refuses to perform some particular scan. The loglevel of daemon is set to maximum.
   WARNING: This log tends to be very extensible and might grow to many megabytes in a while!

   LogRedirection log_file_path

   This default isn't specified by default, and thus there's no application stderr output visible. When specified, this output is redirected to the desired file. This can be useful when debugging issues related to the kernel extension and its interface against the userspace application.

   LogRawScanLines yes_or_no

   This default isn't specified by default, and thus the application log doesn't contain scan-lines from the daemon. Set this default to yes when You want to include the exact form of each processed scanline into the logfile.

   SupportMailAddress email_address

   This default specifies the recipient of all stuff, mailed to Alwil Software using this application. By default, it's 'virus@avast.com', but You might set another recipient here, if You are interrested or if suitable (for example my email, when sending some suspicious MacOS X stuff).

   AfterCloseQueueDelay no_of_seconds

   This default determines how often is the userspace event-queue polled for subsequent processing. By default, it's 0.05, but for debugging purposes, it sometimes suitable to set it to bigger value to increase the probability of some occasional rare flaws, related to event-caching.

   DebugShiftQuits

   The application checks whether the shift is pressed during its start. Thus, when this default is set, we can get rid of auto-launched Avast! by holding shift, etc. Useful for avoiding any situation where the auto-started Avast! causes serious problem. By default, this keyword is not set.

   CheckKauthDelay no_of_seconds

   The delay of kext-polling after the application starts. During this interval, no events will be taken from the kernel. Zero, the default, means no delay and thus immediate after-close scanning. Negative value means infinite delay and thus will effectively disables this mechanism.

   TrialChangeForReport no_of_seconds

   This default defines how often should be the changed trial reported. Upon each session, the daemon report the remaining seconds of trial period, and this change is logged to the 'Activity Log.txt'. But, we can specify how much second is required for this mark, and thus we can avoid bloated logs in the case where the sessions are re-created too fast for some reason. The default is 86400 seconds, and thus only one report per day. This logging might be useful when resolving any trial-related issues.

   
   
   
2. BetaLog.txt
   This file, when enabled, contains very detailed log from the communication channel between the GUI application and the daemon. The file can be found in '~/Library/Application Support/com.avast.MacAvast' directory, and might get quite big in a while, so please don't be surprised what's eating Your free disk space. You might use 'tail -f' over this file to see what was added recently there. When doing a bugreport, please, attach the relevant tail of this file to You mail.
   
   
3. application log
   This is the standard error output from the 'avast!' antivirus application and contains the log from communication between agent and the kernel extension, together with other gui-related events. You might see it when running '/Applications/avast!.app/Contents/MacOS/avast!' manually from a terminal or gdb. This log can be also redirected to any file using LogRedirection default, described above. When doing a bugreport, please, attach the relevant tail of this log to You mail.
   
   
4. system.log
   This is the standard system log, usually found in '/var/log/system.log', and contains some additional low-level messages from the on-access mechanism, mixed with other system-wide messages. When doing a bugreport, please, attach the relevant tail of this log to You mail.
   
   
5. daemon log
   You can look using 'ps -A -w -w' how's the com.avast.MacAvast.MAD daemon launched, then kill it's PID, and launch it manually with the same arguments, but append '-m 0xffffffff -s path_to_log_file'. You can run the daemon from gdb this way too. Now, the daemon will produce activity log from its side too (mutually comparable with BetaLog.txt). Unless the daemon crashes, freezes or has another flaw, this log isn't necessary. Also, this logging can be turned on using the MADLogRedirection default, described above.
   
   
6. daemon freezes, crashes or stops serving particular session
   First, invoke the 'top', and check, whether the daemon still exists as a process and what's its machine time consumption. Try to connect to the daemon manually using 'telnet -u path_to_the_listening_socket', get the proper path from 'ps -A -w -w'. Try to find what file causes the problem (look into BetaLog.txt or daemon log), and in the session, issue commands 'LICENSE PATH path_to_the_valid_license_file', and then 'SCAN path_to_the_problematic_location'. Check the output, when the daemon reports engine errors, the low numbers are equal to the standard lic errno codes, and numbers with base 42000 are avast-specific. The protocol is briefly described here protocol.en.txt, and the avast-specific error codes here errors.txt. When the daemon crashes or freezes, please try to run it under gdb (or attach to the process using 'gdb -p process_pid'), to get the backtrace, or send us the coredump ( first, set 'ulimit -c max_core_size_in_KiB' in Your shell ). Also, we can send You special debug-build of the daemon with more detailed logging and debug messaging on request.
   
   
7. avast! antivirus crashes, freezes or terminates without reason
   In this case, run the application inside GDB and get the application log, or backtrace to the segfaulting point. Also, the crashreport generated by OSX migh explain a lot, when generated, please cut and paste it to You report.
   
   
8. the system performance dropped a lot
   There's probably some problem in the event blacklisting. Have a look into the application log whether there aren't repetitive events to be processed, over a potentially big file, which is due to them scanned again and again, or some huge archive was modified. Because all the processing is asynchronous, such slowdown always means that there's some busy scanning activity behind.