Skip to content

Latest commit

 

History

History
59 lines (41 loc) · 4 KB

CONTRIBUTING.md

File metadata and controls

59 lines (41 loc) · 4 KB
Raw

Contributing to logdissect

Contributions are welcome in the form of code or testing feedback. All contributors are expected to follow our code of conduct.

Index

Testing

User feedback helps logdissect get better. All issues and comments can be directed to the issues page on GitHub, or emailed to dpersonsdev@gmail.com. Please ensure you are using the latest release.

Issues based on bugs should be well documented, with any error message and an explanation of how the issue can be reproduced. Additional information such as Python version and operating system are also useful.

Coding

If you have a bug fix, or an idea for a module, we would love to hear about it! You can start an issue on GitHub, or email the author at dpersonsdev@gmail.com.

All new modules should be based on the dev branch. New modules usually don't require any editing of existing files (except __init__.py files), so conflicts shouldn't be much of an issue. Get in touch beforehand if you need to change other existing files for your module, or if you want to add to logdissect.utils.

Code should run with both Python 2 and 3. Coding style should be as simple and readable as possible. Variable names should tell you exactly what a variable does. Use four spaces for indentation (no tabs), and avoid one-liners; equivalent blocks of code are usually easier to read.

Parser Modules

Creating a parser module is as simple as coming up with a regular expression, and some fields for it to parse. Parse modules are not limited to built-in fields; any field names can be defined. There is an example blank parser in logdissect/parsers/blank.py. Set the datestamp_type attribute for automatic date stamp conversion, which is required for merging and sorting logs. The options for datestamp_type are as follows:

  • standard - Standard syslog date stamps
  • nodate - Time stamps with no date (i.e. tcpdump)
  • iso - ISO8601 timestamps
  • unix - Unix timestamps
  • now - Always set date stamp to time parsed
  • None - Skip conversion

Parse modules also have a post_parse_action method that each entry is passed through after it is parsed. This can be used for separating ports from source and destination hosts, or any other customization. By default, it does nothing.

The name of your parse module should be added to the __all__ variable and imported in logdissect/parsers/__init__.py. More information on parser modules can be found in the API documentation.

Filter Modules

Creating a filter module is a bit more difficult. Check out the filter API documentation, and look at existing filter modules to get an idea of how filters work. There is an example blank filter in logdissect/filters/blank.py. Once you have created a filter module, add it to the all variable and import it in logdissect/filters/__init__.py.

Output Modules

Check out the output API documentation, and look at existing output modules to get an idea of how outputs work. There is an example blank output in logdissect/output/blank.py. Once you have created an output module, add it to the all variable and import it in logdissect/output/__init__.py.

Installing Development Source

To install the latest development version of logdissect from source, follow these instructioons:

Requirements: git, python-setuptools

git clone https://github.com/dogoncouch/logdissect.git
cd logdissect
git checkout dev
sudo make all

Usage

For usage instructions, see README.md.

For API documentation, see README-API.md