Skip to content

Latest commit

 

History

History
131 lines (94 loc) · 6.71 KB

CONTRIBUTING.md

File metadata and controls

131 lines (94 loc) · 6.71 KB

Contributing to Arkime

✨ Glad to see you here! ✨

Just have a question ❓

Where do I start? 🚥

First, checkout the main Arkime README for information on how to build and run Arkime.

Then, get some test data!

  • Make sure node is in your path
  • Install and Start Elasticsearch
  • Use easybutton-build.sh or configure and make to build everything
  • Run make check from the top level directory, this will
    • run npm ci everywhere
    • run tests.pl and tests.pl --viewer in the tests directory (this loads PCAPs)

Note: this will only work if viewer is not already running.

You should now have test data loaded, so let's start the web app:

  • Move to the Arkime viewer directory
  • Run npm ci
  • Move back up to the top level Moloch directory
  • Run npm run viewer:test
  • Now browse to the app at http://localhost:8123

If you want to run Moloch in non-anonymous mode:

  • Move to the top level Moloch directory
  • run npm run viewer:addtestuser
  • run npm run viewer:dev

🕐 On first load, you will likely see this message: "No results or none that match your search within your time range." This is because the data that was loaded is from all time ranges, so make sure you search for ALL times ranges.

For more information about running the Arkime Viewer web application, visit the viewer README.

To contribute to Parliament or WISE, read their READMEs for information on how to build them for development

How do I contribute?

Documentation! 📃

Documentation, READMEs, examples, and FAQs are important. Please help improve and add to them.

Bugs 🐛 🪲 🐜

Before submitting a bug report:

  • Ensure the bug was not already reported by searching for existing issues in Arkime
    • If an issues is already open, make a comment that you are experiencing the same thing and provide any additional details
  • Check the FAQs for a list of common questions and problems

Bugs are tracked as GitHub Issues. Please follow these guidelines when submitting a bug:

  • Provide a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Explain the expected behavior
  • Fill out the issue template completely

Feature Requests ✨

Feature requests include new features and minor improvements to existing functionality.

Feature requests are tracked as GitHub Issues. Please follow these guidelines when submitting a feature request:

  • Please use a fork to submit a pull request for your contribution.
  • Provide a clear and descriptive title
  • Describe the suggested feature in as much detail as possible
  • Use examples to help us understand the use case of the feature
  • If you are requesting a minor improvement, describe the current behavior and why it is not sufficient
  • If possible, provide examples of where this feature exists elsewhere in other tools
  • Follow the directions in the issue template

Pull Requests 💪

We welcome all collaboration! If you can fix it or implement it, please do! 🔨

To better help us review your pull request, please follow these guidelines:

  • Provide a clear and descriptive title
  • Clearly describe the problem and solution
  • Include the relevant issue number(s) if applicable
  • If changes are made to the capture component, verify all tests in the tests direction pass by running ./tests.pl
  • Run npm run lint from the top level directory and correct any errors
  • Additionally, for any viewer or parliament changes, verify that all UI tests pass by runnning ./tests.pl --viewer
  • The README file in the tests directory provides additional information on the test cases

API Documentation

The API is documented using jsdoc and jsdoc2md.

If you update or create an API, please document it thoroughly with these items:

  1. METHOD - endpoint (e.g. GET - /api/sessions)
  2. Description
  3. Name the endpoint with @name endpointname (e.g. sessions). This is the name that will be reflected in the title of the endpoint and the table of contents.
  4. List the parameters including any defaults with @param (e.g. @param {number} date=1 - The number of hours of data to return (-1 means all data). Defaults to 1)
  5. Describe the return value(s) with @returns (e.g. @returns {array} data - The list of sessions with the requested fields)

The documentation lives on our website at arkime.com/api. It is generated using the code documentation. Follow these steps to update the API documentation:

  1. Check out the arkimeweb repository in the same parent directory as the Arkime repository.
  2. Run npm run viewer:doc from the arkime directory. If you checked out the arkimeweb repository into a different location, you can run npm run viewer:doc-location -- <path/to/arkimeweb/_wiki/api_docs.md>.
  3. Run the arkime website locally (find out how here) to make sure all of your documentation is correct.
  4. Make a PR to arkime and arkimeweb with your changes.

Upgrading Cyberchef

  1. Update the CyberChef version ("CYBERCHEFVERSION") in viewer/viewer.js
  2. Update the CyberChef version in viewer/Makefile.in (there are two version numbers on line 23)
  3. Run make in viewer or download the new version of the CyberChef zip file manually to the viewer/public directory
  4. Unzip and copy CyberChef_v*.html to viewer/public/CyberChef_v*.html
  5. Add <base href="./cyberchef/" /> in the <head> of viewer/public/CyberChef_v*.html
  6. Add the script section from the previous viewer/public/cyberchef.html file before the end </body></html> tags at the end of viewer/public/CyberChef_v*.html
  7. Add <meta name="referrer" content="no-referrer"> to viewer/public/CyberChef_v*.html
  8. Delete the old CyberChef zip file
  9. Delete the old CyberChef html file
  10. Rename viewer/public/CyberChef_v*.html file to viewer/public/cyberchef.html

❤️ Thanks,

Andy & Elyse