Documentation for VMClarity

CODE_OF_CONDUCT.md

@@ -0,0 +1,79 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [[email protected]][conduct-email]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+[conduct-email]: mailto:[email protected]
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# How to Contribute
+
+Thanks for your interest in contributing to VMClarity! Here are a few general guidelines on contributing and
+reporting bugs that we ask you to review. Following these guidelines helps to communicate that you respect the time of
+the contributors managing and developing this open source project. In return, they should reciprocate that respect in
+addressing your issue, assessing changes, and helping you finalize your pull requests. In that spirit of mutual respect,
+we endeavor to review incoming issues and pull requests within 10 days, and will close any lingering issues or pull
+requests after 60 days of inactivity.
+
+Please note that all of your interactions in the project are subject to our [Code of Conduct](/CODE_OF_CONDUCT.md). This
+includes creation of issues or pull requests, commenting on issues or pull requests, and extends to all interactions in
+any real-time space e.g., Slack, Discord, etc.
+
+## Table Of Contents
+
+- [Troubleshooting and Debugging](#troubleshooting-and-debugging)
+- [Reporting Issues](#reporting-issues)
+- [Development](#development)
+  - [Generating API code](#generating-api-code)
+  - [Building VMClarity Binaries](#building-vmclarity-binaries)
+  - [Building VMClarity Containers](#building-vmclarity-containers)
+  - [Linting](#linting)
+  - [Unit Tests](#unit-tests)
+  - [Testing End to End](#testing-end-to-end)
+- [Sending Pull Requests](#sending-pull-requests)
+- [Other Ways to Contribute](#other-ways-to-contribute)
+
+## Troubleshooting and Debugging
+
+Please see the troubleshooting and debugging guide [here](/docs/troubleshooting.md).
+
+## Reporting Issues
+
+Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our
+[issues list](https://github.com/openclarity/vmclarity/issues).
+
+When creating a new issue, please be sure to include a **title and clear description**, as much relevant information as
+possible, and, if possible, a test case.
+
+**If you discover a security bug, please do not report it through GitHub. Instead, please see security procedures in
+[SECURITY.md](/SECURITY.md).**
+
+## Development
+
+### Building VMClarity Binaries
+
+Makefile targets are provided to compile and build the VMClarity binaries.
+`make build` can be used to build all of the components, but also specific
+targets are provided, for example `make build-cli` and `make build-backend` to
+build the specific components in isolation.
+
+### Building VMClarity Containers
+
+`make docker` can be used to build the VMClarity containers for all of the
+components. Specific targets for example `make docker-cli` and `make
+docker-backend` are also provided.
+
+`make push-docker` is also provided as a shortcut for building and then
+publishing the VMClarity containers to a registry. You can override the
+destination registry like:
+
+```
+DOCKER_REGISTRY=docker.io/tehsmash make push-docker
+```
+
+You must be logged into the docker registry locally before using this target.
+
+### Linting
+
+`make lint` can be used to run the required linting rules over the code.
+golangci-lint rules and config can be viewed in the `.golangcilint` file in the
+root of the repo.
+
+`make fix` is also provided which will resolve lint issues which are
+automaticlly fixable for example format issues.
+
+`make license` can be used to validate that all the files in the repo have the
+correctly formatted license header.
+
+To lint the cloudformation template, `cfn-lint` can be used, see
+https://github.com/aws-cloudformation/cfn-lint#install for instructions on how
+to install it for your system.
+
+### Unit tests
+
+`make test` can be used run all the unit tests in the repo. Alternatively you
+can use the standard go test CLI to run a specific package or test like:
+
+```
+go test ./cli/cmd/... -run Test_isSupportedFS
+```
+
+### Generating API code
+
+After making changes to the API schema in `api/openapi.yaml`, you can run `make
+api` to regenerate the model, client and server code.
+
+### Testing End to End
+
+For details on how to test VMClarity end to end please see the End to End
+testing guide [here](/docs/test_e2e.md).
+
+## Sending Pull Requests
+
+Before sending a new pull request, take a look at existing pull requests and issues to see if the proposed change or fix
+has been discussed in the past, or if the change was already implemented but not yet released.
+
+We expect new pull requests to include tests for any affected behavior, and, as we follow semantic versioning, we may
+reserve breaking changes until the next major version release.
+
+## Other Ways to Contribute
+
+We welcome anyone that wants to contribute to VMClarity to triage and reply to open issues to help troubleshoot
+and fix existing bugs. Here is what you can do:
+
+- Help ensure that existing issues follows the recommendations from the _[Reporting Issues](#reporting-issues)_ section,
+  providing feedback to the issue's author on what might be missing.
+- Review and update the existing content of our [Wiki](https://github.com/openclarity/vmclarity/wiki) with up-to-date
+  instructions and code samples.
+- Review existing pull requests, and testing patches against real existing applications that use VMClarity.
+- Write a test, or add a missing test case to an existing test.
+
+Thanks again for your interest on contributing to VMClarity!
+
+:heart:

README.md

@@ -3,38 +3,53 @@
 VMClarity is a tool for agentless detection and management of Virtual Machine
 Software Bill Of Materials (SBOM) and vulnerabilities
 
-To install vmclarity in your AWS account [Click Here](https://eu-central-1.console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/create/review?templateUrl=https://raw.githubusercontent.com/openclarity/vmclarity/main/installation/aws/VmClarity.cfn&stackName=VmClarity)
-
 ## Table of Contents
 
-- [How to debug the Scanner VMs](#how-to-debug-the-scanner-vms)
-  - [AWS](#debug-scanner-VM-on-AWS)
+- [Getting Started](#getting-started)
+  - [Installing on AWS](#installing-on-aws)
+  - [Accessing the API](#accessing-the-api)
+- [Security](#security)
+- [Contributing](#contributing)
+- [Code of Conduct](#code-of-conduct)
+- [License](#license)
+
+## Getting Started
 
-## How to debug the Scanner VMs
+### Installing on AWS
 
-How to debug the Scanner VMs can differ per provider these are documented
-below.
+1. Download the cloud-formation from the VMClarity Github release
+2. Go to AWS console Cloudformation for your choosen region
+3. Create a stack with new resources
+4. Upload the downloaded template
+5. Walk through the wizard
+6. Monitor install from the cloud-formation page
+7. Get the VMClarity public IP address from the Outputs tab.
 
-### Debug Scanner VM on AWS
+### Accessing the API
 
-On AWS VMClarity is configured to create the Scanner VMs with the same key-pair
-that the VMClarity server has. The Scanner VMs run in a private network,
-however the VMClarity Server can be used as a bastion/jump host to reach them
-via SSH.
+To access the API, a tunnel to the HTTP ports must be opened using the
+VMClarity server as a bastion.
 
 ```
-ssh -i <key-pair private key> -J ubuntu@<vmclarity server public IP> ubuntu@<scanner VM private IP address>
+ssh -N -L 8888:localhost:8888 ubuntu@<VMClarity public IP address>
 ```
 
-Once SSH access has been established, the status of the VM's start up
-configuration can be debugged by checking the cloud-init logs:
+Once this has been run the VMClarity API can be access on localhost:8888. For example:
 
 ```
-sudo journalctl -u cloud-final
+curl http://localhost:8888/api/scanConfigs
 ```
 
-And the vmclarity-scanner service logs:
+## Contributing
 
-```
-sudo journalctl -u vmclarity-scanner
-```
+If you are ready to jump in and test, add code, or help with documentation,
+please follow the instructions on our [contributing guide](/CONTRIBUTING.md)
+for details on how to open issues, setup VMClarity for development and test.
+
+## Code of Conduct
+
+You can view our code of conduct [here](/CODE_OF_CONDUCT.md).
+
+## License
+
+[Apache License, Version 2.0](/LICENSE)

SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policies and Procedures
+
+This document outlines security procedures and general policies for the
+VMClarity project.
+
+- [Reporting a Bug](#reporting-a-bug)
+- [Disclosure Policy](#disclosure-policy)
+- [Comments on this Policy](#comments-on-this-policy)
+
+## Reporting a Bug
+
+The VMClarity team and community take all security bugs in
+VMClarity seriously. Thank you for improving the security of
+VMClarity. We appreciate your efforts and responsible disclosure and
+will make every effort to acknowledge your contributions.
+
+Report security bugs by emailing `[email protected]`.
+
+The lead maintainer will acknowledge your email within 48 hours, and will send a
+more detailed response within 48 hours indicating the next steps in handling
+your report. After the initial reply to your report, the security team will
+endeavor to keep you informed of the progress towards a fix and full
+announcement, and may ask for additional information or guidance.
+
+## Disclosure Policy
+
+When the security team receives a security bug report, they will assign it to a
+primary handler. This person will coordinate the fix and release process,
+involving the following steps:
+
+- Confirm the problem and determine the affected versions.
+- Audit code to find any potential similar problems.
+- Prepare fixes for all releases still under maintenance. These fixes will be
+  released as quickly as possible.
+
+## Comments on this Policy
+
+If you have suggestions on how this process could be improved please submit a
+pull request.