Skip to content

Commit

Permalink
readme
Browse files Browse the repository at this point in the history
mmguero committed Dec 18, 2024

Verified

This commit was signed with the committer’s verified signature.
armancodv Arman Kolahan
1 parent af97c7e commit f172b95
Showing 3 changed files with 7 additions and 8 deletions.
2 changes: 1 addition & 1 deletion docs/capabilities-and-limitations.md
Original file line number Diff line number Diff line change
@@ -112,7 +112,7 @@ In short, Malcolm provides an easily deployable traffic analysis tool suite for
+ The organizations supporting Malcolm's development do not offer paid professional services or any contract-based support. Any support provided is done the same way most other open-source projects do so, which is through GitHub, for example:
* [Community discussions board](https://github.com/cisagov/Malcolm/discussions)
* [Issue and feature tracking](https://github.com/cisagov/malcolm/issues?q=is%3Aissue+is%3Aopen+-label%3Atraining)
* [Project roadmap tracking](https://github.com/orgs/idaholab/projects/1)
* [Project roadmap tracking](https://github.com/orgs/cisagov/projects/98)
+ Beyond engagement via the forums listed here, no expectation of any particular level of support should be assumed.
* User experience/UI/intuitive
- Malcolm's user-friendly analyst-facing interfaces are accessible via an easy-to-nagivate [landing page](images/screenshots/malcolm_landing_page.png).
3 changes: 2 additions & 1 deletion docs/contributing-guide.md
Original file line number Diff line number Diff line change
@@ -27,4 +27,5 @@ It is recommended before reviewing this guide to read the documentation on [cust
* [Carved file scanners](contributing-file-scanners.md#Scanners)
* [Style](contributing-style.md#Style)
* [Using GitHub runners to build Malcolm images](contributing-github-runners.md#GitHubRunners)
* [Preparing a Malcolm Release](contributing-release-prep.md)
* [Preparing a Malcolm Release](contributing-release-prep.md)
* [`malcolm-test`: Malcolm System Tests](contributing-malcolm-test.md#MalcolmTest)
10 changes: 4 additions & 6 deletions docs/contributing-release-prep.md
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@ This document outlines the steps a Malcolm developer goes through to publish a r

## 1. Review the project milestone and the branch from which the release will be staged

Malcolm tracks issues (whether they be bugs, new features, enhancements, etc.) for release milestones using a [GitHub project](https://github.com/orgs/idaholab/projects/1). Before building release candidate images, Romeo reviews the items for the upcoming release in the corresponding project milestone and ensures that all items assigned to it have their status set to **Done**, each item having been completed and tested locally by the developer to which the issue was assigned.
Malcolm tracks issues (whether they be bugs, new features, enhancements, etc.) for release milestones using a [GitHub project](https://github.com/orgs/cisagov/projects/98). Before building release candidate images, Romeo reviews the items for the upcoming release in the corresponding project milestone and ensures that all items assigned to it have their status set to **Done**, each item having been completed and tested locally by the developer to which the issue was assigned.

Romeo also ensures that all work towards this release has been pulled into the branch on his fork from which the release will be cut. If [pull requests]({{ site.github.repository_url }}/pulls) have been submitted upstream which resolve the issues assigned to this release, those pull requests should be merged into the branch at `romeogdetlevjr/Malcolm`, whether they were submitted initially against that fork or pulled in manually by Romeo as part of this release process. Pull requests are not accepted directly into the `main` branch of the official [upstream fork]({{ site.github.repository_url }}). In other words, the branch of Malcolm in Romeo's development fork should contain **everything** that is going to comprise this release of Malcolm.

@@ -32,13 +32,11 @@ Romeo carefully reviews the documentation on this [convenience helper script](co

Now that he's got the `.iso` files for Malcolm and Hedgehog Linux, Romeo fires up some virtualization software ([VMware Workstation](https://www.vmware.com/products/desktop-hypervisor/workstation-and-fusion), [VirtualBox](https://www.virtualbox.org/), or, his personal favorite, [virt-manager](https://virt-manager.org/)) and installs the ISOs into their respective VMs. He makes sure his VMs are configured to meet the [recommended system requirements](system-requirements.md#SystemRequirements). He follows the [end-to-end Malcolm and Hedgehog Linux ISO Installation](malcolm-hedgehog-e2e-iso-install.md#InstallationExample) example in the documentation to install and configure Malcolm and Hedgehog Linux, resulting in a configuration where the VMs are successfully communicating with each other.

Part of Romeo's testing includes uploading PCAP files to test the parsers for Malcolm's [supported protocols](protocols.md#Protocols), so he uses a [set of PCAP files](https://github.com/idaholab/Malcolm-test-Artifacts) for this purpose.
Romeo knows that verifying live traffic capture is an important part of testing both [Hedgehog Linux](live-analysis.md#Hedgehog) and [Malcolm](live-analysis.md#LocalPCAP). He has used a few open-source tools to generate "real" live Internet traffic in his VMs, including [PartyLoud](https://github.com/mmguero-dev/PartyLoud), [alphasoc/flightsim](https://github.com/alphasoc/flightsim), and [3CORESec/testmynids.org](https://github.com/3CORESec/testmynids.org). He downloads these utilities into both VMs and configures both Malcolm and Hedgehog Linux to capture the live traffic generated, and validates the resulting traffic metadata generated by Zeek, Suricata, and Arkime looks correct in both [OpenSearch Dashboards](dashboards.md#Dashboards) and [Arkime](arkime.md#Arkime). He makes a special note to use [Arkime's sessions interface](arkime.md#ArkimeSessions) to retrieve a PCAP payload for an Arkime session captured on each VM.

He also knows that verifying live traffic capture is an important part of testing both [Hedgehog Linux](live-analysis.md#Hedgehog) and [Malcolm](live-analysis.md#LocalPCAP). He has used a few open-source tools to generate "real" live Internet traffic in his VMs, including [PartyLoud](https://github.com/mmguero-dev/PartyLoud), [alphasoc/flightsim](https://github.com/alphasoc/flightsim), and [3CORESec/testmynids.org](https://github.com/3CORESec/testmynids.org). He downloads these utilities into both VMs and configures both Malcolm and Hedgehog Linux to capture the live traffic generated.
### `malcolm-test`: Malcolm System Tests

Having [uploaded](upload.md#Upload) a variety of PCAP files and configured [live traffic analysis](live-analysis.md), Romeo validates the resulting traffic metadata generated by Zeek, Suricata, and Arkime looks correct in both [OpenSearch Dashboards](dashboards.md#Dashboards) and [Arkime](arkime.md#Arkime). He makes a special note to use [Arkime's sessions interface](arkime.md#ArkimeSessions) to retrieve a PCAP payload for an Arkime session captured on each VM.

Romeo knows that soon™ the Malcolm project will include a [robust automated system testing framework](https://github.com/idaholab/Malcolm/issues/11), but until then he realizes it's on him to do his best to ensure the quality of this Malcolm release. He carefully reviews and tests each issue assigned to this milestone on the [GitHub project board](https://github.com/orgs/idaholab/projects/1).
In addition to the `.iso` spot checks described above, Romeo uses [`malcolm-test`](contributing-malcolm-test.md#MalcolmTest) to ensure that the release candidate does not introduce any regressions. He also carefully reviews each issue assigned to this milestone on the [GitHub project board](https://github.com/orgs/cisagov/projects/98) and verifies that new [tests](https://github.com/idaholab/Malcolm-Test/tree/main/src/maltest/tests) were [created](https://github.com/idaholab/Malcolm-test?tab=readme-ov-file#TestCreation) to cover new features and bug fixes wherever possible.

## 6. Build Hedgehog Linux Raspberry Pi image

0 comments on commit f172b95

Please sign in to comment.