From 42725c142ace74b76b81d6a280b71b0fdd4eac75 Mon Sep 17 00:00:00 2001 From: Sam Betts Date: Wed, 8 Mar 2023 11:15:10 +0000 Subject: [PATCH 1/3] Lay foundations for releasing and installing VMClarity --- .github/workflows/ci.yml | 2 +- .github/workflows/main-merge.yml | 13 +++ .github/workflows/release.yaml | 89 +++++++++++++++++++ .github/workflows/reusable-build-and-push.yml | 4 +- .goreleaser.yml | 48 ++++++++++ installation/aws/VmClarity.cfn | 6 +- 6 files changed, 156 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/main-merge.yml create mode 100644 .github/workflows/release.yaml create mode 100644 .goreleaser.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 993bd1d3e..71eb8a462 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,4 +33,4 @@ jobs: with: image_tag: ${{ github.sha }} push: false - upload: false \ No newline at end of file + upload: false diff --git a/.github/workflows/main-merge.yml b/.github/workflows/main-merge.yml new file mode 100644 index 000000000..0fba60da0 --- /dev/null +++ b/.github/workflows/main-merge.yml @@ -0,0 +1,13 @@ +name: Main merge +on: + push: + branches: + - main + +jobs: + build_and_push: + uses: ./.github/workflows/reusable-build-and-push.yml + with: + image_tag: latest + push: true + upload: false diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 000000000..d00984676 --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,89 @@ +name: Release +on: + push: + tags: + - "v[0-9]+.[0-9]+.[0-9]+" + +env: + GO_VERSION: 1.20 + +jobs: + verification: + name: Verification + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Set up Go + uses: actions/setup-go@v3 + with: + go-version: ${{ env.GO_VERSION }} + + - name: Check licenses + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: make license-check + + - name: Run verification + run: make check + + build_and_push: + needs: verification + name: Build & Push + uses: ./.github/workflows/reusable-build-and-push.yml + with: + image_tag: ${{ github.ref_name }} + push: true + upload: false + + main_release: + needs: build_and_push + name: Release + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Render cloudformation + id: render_cloudformation + run: | + sed -i 's/ghcr.io\/openclarity\/vmclarity-backend:latest/ghcr.ioi\/openclarity\/vmclarity-backend:${{ github.ref_name }}/g' installation/aws/VmClarity.cfn + sed -i 's/ghcr.io\/openclarity\/vmclarity-cli:latest/ghcr.ioi\/openclarity\/vmclarity-cli:${{ github.ref_name }}/g' installation/aws/VmClarity.cfn + + - name: Set up Go + uses: actions/setup-go@v3 + with: + go-version: ${{ env.GO_VERSION }} + + - name: Run GoReleaser + uses: goreleaser/goreleaser-action@v4 + with: + version: v1.16.0 + args: release --clean + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # TODO(sambetts) We need to publish a tag in the format "api/" tag + # so that go mod is able to import the api module without overriding. We need + # to work out how to do this cleanly from github actions on release so that + # we don't need to manage it manually. We could do something this which will + # create another release: + # + # api_release: + # needs: release + # name: Release API Module + # runs-on: ubuntu-latest + # steps: + # - name: Checkout + # uses: actions/checkout@v3 + # with: + # fetch-depth: 0 + # - name: Release API + # uses: softprops/action-gh-release@v1 + # with: + # name: VMClarity {{ github.ref }} API + # body: See main {{ github.ref }} release for release notes. + # tag_name: api/{{ github.ref }} diff --git a/.github/workflows/reusable-build-and-push.yml b/.github/workflows/reusable-build-and-push.yml index ac630b2b8..d434e37a4 100644 --- a/.github/workflows/reusable-build-and-push.yml +++ b/.github/workflows/reusable-build-and-push.yml @@ -28,7 +28,7 @@ jobs: id: timestamp run: echo "::set-output name=timestamp::$(date -u +'%Y-%m-%dT%H:%M:%SZ')" - vmclarity: + vmclarity-backend: needs: timestamp runs-on: ubuntu-latest steps: @@ -62,7 +62,7 @@ jobs: uses: docker/build-push-action@v4 with: context: . - tags: ghcr.io/openclarity/vmclarity:${{ inputs.image_tag }} + tags: ghcr.io/openclarity/vmclarity-backend:${{ inputs.image_tag }} file: Dockerfile.backend push: ${{ inputs.push }} outputs: "${{ env.OUTPUTS }}" diff --git a/.goreleaser.yml b/.goreleaser.yml new file mode 100644 index 000000000..6bc6b399b --- /dev/null +++ b/.goreleaser.yml @@ -0,0 +1,48 @@ +builds: + - + id: "cli" + dir: cli + binary: vmclarity-cli + env: + - CGO_ENABLED=0 + ldflags: "-s -w -X github.com/openclarity/vmclarity/cli/pkg.GitRevision={{ .Version }}" + goos: + - linux + - darwin + goarch: + - amd64 + - arm64 + +archives: + - + id: "cli" + name_template: "{{ .Binary }}-{{ .Version }}-{{ .Os }}-{{ .Arch }}" + + # Additional files/template/globs we want to add to the archive. + files: + - LICENSE + - README.md + +checksum: + name_template: 'checksums.txt' + +# Change the default artifacts folder +dist: goreleaser_artifacts + +snapshot: + name_template: "{{ incpatch .Version }}-next" + +changelog: + sort: asc + use: github-native + filters: + exclude: + - '^docs:' + - '^test:' + - '^workflow:' + - Merge pull request + - Merge remote-tracking branch + +release: + extra_files: + - glob: ./installation/aws/VmClarity.cfn diff --git a/installation/aws/VmClarity.cfn b/installation/aws/VmClarity.cfn index c4843d6f3..f90f988d1 100644 --- a/installation/aws/VmClarity.cfn +++ b/installation/aws/VmClarity.cfn @@ -163,7 +163,7 @@ Resources: LOCAL_DB_PATH=/data/vmclarity.db BACKEND_REST_ADDRESS=__BACKEND_REST_ADDRESS__ BACKEND_REST_PORT=8888 - SCANNER_CONTAINER_IMAGE=erezfish/vmclarity-cli:mount + SCANNER_CONTAINER_IMAGE=ghcr.io/openclarity/vmclarity-cli:latest - JobImageID: !FindInMap - AWSRegionArch2AMI - !Ref "AWS::Region" @@ -212,13 +212,13 @@ Resources: ExecStartPre=-/usr/bin/docker stop %n ExecStartPre=-/usr/bin/docker rm %n ExecStartPre=/usr/bin/mkdir -p /opt/vmclarity - ExecStartPre=/usr/bin/docker pull erezfish/vmclarity-backend:mount + ExecStartPre=/usr/bin/docker pull ghcr.io/openclarity/vmclarity-backend:latest ExecStart=/usr/bin/docker run \ --rm --name %n \ -p 0.0.0.0:8888:8888/tcp \ -v /opt/vmclarity:/data \ --env-file /etc/vmclarity/config.env \ - erezfish/vmclarity-backend:mount run --log-level info + ghcr.io/openclarity/vmclarity-backend:latest run --log-level info [Install] WantedBy=multi-user.target From 14e830098dfdfb76dfab224137ea5b7f45362dbf Mon Sep 17 00:00:00 2001 From: Sam Betts Date: Tue, 7 Mar 2023 17:05:15 +0000 Subject: [PATCH 2/3] Documentation for VMClarity --- CODE_OF_CONDUCT.md | 79 +++++++++++++++ CONTRIBUTING.md | 125 ++++++++++++++++++++++++ README.md | 55 +++++++---- SECURITY.md | 39 ++++++++ scanConfig.json => docs/scanConfig.json | 0 test_e2e.md => docs/test_e2e.md | 60 +++++++----- docs/troubleshooting.md | 36 +++++++ 7 files changed, 350 insertions(+), 44 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md rename scanConfig.json => docs/scanConfig.json (100%) rename test_e2e.md => docs/test_e2e.md (65%) create mode 100644 docs/troubleshooting.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..8af3c7998 --- /dev/null +++ b/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 [oss-conduct@cisco.com][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:oss-conduct@cisco.com + +## 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..6c9b06a40 --- /dev/null +++ b/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: diff --git a/README.md b/README.md index 239b4301d..c94a211cc 100644 --- a/README.md +++ b/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 -J ubuntu@ ubuntu@ +ssh -N -L 8888:localhost:8888 ubuntu@ ``` -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) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..42e992c12 --- /dev/null +++ b/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 `oss-security@cisco.com`. + +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. diff --git a/scanConfig.json b/docs/scanConfig.json similarity index 100% rename from scanConfig.json rename to docs/scanConfig.json diff --git a/test_e2e.md b/docs/test_e2e.md similarity index 65% rename from test_e2e.md rename to docs/test_e2e.md index c74764e39..9a8ef7331 100644 --- a/test_e2e.md +++ b/docs/test_e2e.md @@ -1,12 +1,23 @@ -# Update and install the cloud formation +# End to End testing guide -## Build the containers and publish them to your docker hub +## Table of Contents + +- [Installing a specific VMClarity build on AWS](#installing-a-specific-vmclarity-build-on-aws) + - [1. Build the containers and publish them to your docker registry](#1-build-the-containers-and-publish-them-to-your-docker-registry) + - [2. Update installation/aws/VMClarity.cfn](#2-update-installationawsvmclaritycfn) + - [3. Install VMClarity cloudformation](#3-install-vmclarity-cloudformation) + - [4. Ensure that VMClarity backend is working correctly](#4-ensure-that-vmclarity-backend-is-working-correctly) +- [Performing an end to end test](#performing-an-end-to-end-test) + +## Installing a specific VMClarity build on AWS + +### 1. Build the containers and publish them to your docker registry ``` -DOCKER_REGISTRY= make push-docker +DOCKER_REGISTRY= make push-docker ``` -## Update installation/aws/VMClarity.cfn +### 2. Update installation/aws/VMClarity.cfn Update the cloud formation with the pushed docker images, for example: @@ -15,7 +26,7 @@ Update the cloud formation with the pushed docker images, for example: DATABASE_DRIVER=LOCAL BACKEND_REST_ADDRESS=__BACKEND_REST_ADDRESS__ BACKEND_REST_PORT=8888 -- SCANNER_CONTAINER_IMAGE=tehsmash/vmclarity-cli:dc2d75a10e5583e97f516be26fcdbb484f98d5c3 +- SCANNER_CONTAINER_IMAGE=ghcr.io/openclarity/vmclarity-cli:latest + SCANNER_CONTAINER_IMAGE=tehsmash/vmclarity-cli:9bba94334c1de1aeed63ed12de3784d561fc4f1b - JobImageID: !FindInMap - AWSRegionArch2AMI @@ -24,40 +35,41 @@ Update the cloud formation with the pushed docker images, for example: ExecStartPre=-/usr/bin/docker stop %n ExecStartPre=-/usr/bin/docker rm %n ExecStartPre=/usr/bin/mkdir -p /opt/vmclarity -- ExecStartPre=/usr/bin/docker pull tehsmash/vmclarity-backend:dc2d75a10e5583e97f516be26fcdbb484f98d5c3 +- ExecStartPre=/usr/bin/docker pull ghcr.io/openclarity/vmclarity-backend:latest + ExecStartPre=/usr/bin/docker pull tehsmash/vmclarity-backend:9bba94334c1de1aeed63ed12de3784d561fc4f1b ExecStart=/usr/bin/docker run \ --rm --name %n \ -p 0.0.0.0:8888:8888/tcp \ -v /opt/vmclarity:/data \ --env-file /etc/vmclarity/config.env \ -- tehsmash/vmclarity-backend:dc2d75a10e5583e97f516be26fcdbb484f98d5c3 run --log-level info +- ghcr.io/openclarity/vmclarity-backend:latest run --log-level info + tehsmash/vmclarity-backend:9bba94334c1de1aeed63ed12de3784d561fc4f1b run --log-level info [Install] WantedBy=multi-user.target ``` -# Go to AWS -> Cloudformation and create a stack. +### 3. Install VMClarity cloudformation -* Ensure you have an SSH key pair uploaded to AWS Ec2 -* Go to CloudFormation -> Create Stack -> From Template. -* Upload the modified VMClarity.cfn -* Follow the wizard through to the end -* Wait for install to complete +1. Ensure you have an SSH key pair uploaded to AWS Ec2 +2. Go to CloudFormation -> Create Stack -> Upload template. +3. Upload the modified VMClarity.cfn +4. Follow the wizard through to the end +5. Wait for install to complete -# Ssh to the VMClarity server +### 4. Ensure that VMClarity backend is working correctly -* Get the IP address from the CloudFormation stack's Output Tab -* `ssh ubuntu@` -* Check the VMClarity Logs - ``` - sudo journalctl -u vmclarity - ``` +1. Get the IP address from the CloudFormation stack's Output Tab +2. `ssh ubuntu@` +3. Check the VMClarity Logs + + ``` + sudo journalctl -u vmclarity + ``` -# Create Scan Config +## Performing an end to end test -1. Copy the scanConfig.json into the ubuntu user's home directory +1. Copy the example [scanConfig.json](/docs/scanConfig.json) into the ubuntu user's home directory ``` scp scanConfig.json ubuntu@:~/scanConfig.json @@ -138,10 +150,10 @@ Update the cloud formation with the pushed docker images, for example: curl -X POST http://localhost:8888/api/scanConfigs -H 'Content-Type: application/json' -d @scanConfig.json ``` -4. Watch the VMClarity logs again +4. Check VMClarity logs to ensure that everything is performing as expected ``` - sudo journalctl -u vmclarity -f + sudo journalctl -u vmclarity ``` 5. Monitor the scan results diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..193df724f --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,36 @@ +# Troubleshooting and debugging VMClarity + +## Table of Contents + +- [How to debug the Scanner VMs](#how-to-debug-the-scanner-vms) + - [AWS](#debug-scanner-VM-on-AWS) + +## How to debug the Scanner VMs + +How to debug the Scanner VMs can differ per provider these are documented +below. + +### Debug Scanner VM on AWS + +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. + +``` +ssh -i -J ubuntu@ ubuntu@ +``` + +Once SSH access has been established, the status of the VM's start up +configuration can be debugged by checking the cloud-init logs: + +``` +sudo journalctl -u cloud-final +``` + +And the vmclarity-scanner service logs: + +``` +sudo journalctl -u vmclarity-scanner +``` + From 85bf54997a86245fda37b0b42dd73c773ffa5f0f Mon Sep 17 00:00:00 2001 From: Sam Betts Date: Wed, 8 Mar 2023 12:31:09 +0000 Subject: [PATCH 3/3] Update repo settings, templates and introduce stale bot --- .github/ISSUE_TEMPLATE/BUG_REPORT.md | 36 ++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 25 ++++++---- .github/PULL_REQUEST_TEMPLATE.md | 26 ++++++++++ .github/settings.yml | 17 ++++++- .github/stale.yml | 58 +++++++++++++++++++++++ .github/workflows/release.yaml | 4 +- README.md | 1 - 7 files changed, 153 insertions(+), 14 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/BUG_REPORT.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/stale.yml diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md new file mode 100644 index 000000000..8eaadeae5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -0,0 +1,36 @@ +--- +name: Bug Report +about: Report a bug to help us improve +title: '' +labels: '' +assignees: '' + +--- + +## Description + +Please provide a description of the problem. + +## Expected Behavior + +Please describe what you expected would happen. + +## Actual Behavior + +Please describe what happened instead. + +## Affected Version + +Please provide the version number where this issue was encountered. + +## Steps to Reproduce + +1. First step +1. Second step +1. etc. + +## Checklist + + +- [ ] I have read the [contributing guidelines](/CONTRIBUTING.md) +- [ ] I have verified this does not duplicate an existing issue diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7d6..2af6aba22 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,20 +1,25 @@ --- -name: Feature request -about: Suggest an idea for this project +name: Feature Request +about: Suggest a feature for this project title: '' labels: '' assignees: '' --- -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] +## Problem Statement -**Describe the solution you'd like** -A clear and concise description of what you want to happen. +Please describe the problem to be addressed by the proposed feature. -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. +## Proposed Solution -**Additional context** -Add any other context or screenshots about the feature request here. +Please describe what you envision the solution to this problem would look like. + +## Alternatives Considered + +Please briefly describe which alternatives, if any, have been considered, including merits of alternate approaches and +tradeoffs being made. + +## Additional Context + +Please provide any other information that may be relevant. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..784f0a0b3 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## Description + +Please provide a meaningful description of what this change will do, or is for. Bonus points for including links to +related issues, other PRs, or technical references. + +Note that by _not_ including a description, you are asking reviewers to do extra work to understand the context of this +change, which may lead to your PR taking much longer to review, or result in it not being reviewed at all. + +## Type of Change + +- [ ] Bug Fix +- [ ] New Feature +- [ ] Breaking Change +- [ ] Refactor +- [ ] Documentation +- [ ] Other (please describe) + +## Checklist + +- [ ] I have read the [contributing guidelines](/CONTRIBUTING.md) +- [ ] Existing issues have been referenced (where applicable) +- [ ] I have verified this change is not present in other open pull requests +- [ ] Functionality is documented +- [ ] All code style checks pass +- [ ] New code contribution is covered by automated tests +- [ ] All new and existing tests pass diff --git a/.github/settings.yml b/.github/settings.yml index 3bbbdd60a..4166a45a7 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -8,7 +8,7 @@ repository: description: VMClarity is a tool for agentless detection and management of Virtual Machine Software Bill Of Materials (SBOM) and vulnerabilities # A URL with more information about the repository -# homepage: + homepage: openclarity.io # Updates the default branch for this repository. default_branch: main @@ -21,6 +21,21 @@ repository: # vulnerability alerts. enable_vulnerability_alerts: true + # Either `true` to allow squash-merging pull requests, or `false` to prevent + # squash-merging. + allow_squash_merge: true + + # Either `true` to allow merging pull requests with a merge commit, or `false` + # to prevent merging pull requests with merge commits. + allow_merge_commit: false + + # Either `true` to allow rebase-merging pull requests, or `false` to prevent + # rebase-merging. + allow_rebase_merge: true + + # Either `true` to enable automatic deletion of branches on merge, or `false` to disable + delete_branch_on_merge: false + # See https://docs.github.com/en/rest/reference/teams#add-or-update-team-repository-permissions for available options teams: - name: vmclarity-admins diff --git a/.github/stale.yml b/.github/stale.yml new file mode 100644 index 000000000..78bcc61c6 --- /dev/null +++ b/.github/stale.yml @@ -0,0 +1,58 @@ +# Configuration for probot-stale - https://github.com/probot/stale + +# Number of days of inactivity before an Issue or Pull Request becomes stale +daysUntilStale: 60 + +# Number of days of inactivity before an Issue or Pull Request with the stale label is closed. +# Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale. +daysUntilClose: 14 + +# Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled) +onlyLabels: [] + +# Issues or Pull Requests with these labels will never be considered stale. Set to `[]` to disable +exemptLabels: [] + +# Set to true to ignore issues in a project (defaults to false) +exemptProjects: false + +# Set to true to ignore issues in a milestone (defaults to false) +exemptMilestones: false + +# Set to true to ignore issues with an assignee (defaults to false) +exemptAssignees: false + +# Label to use when marking as stale +staleLabel: stale + +# Comment to post when marking as stale. Set to `false` to disable +markComment: > + This issue has been automatically marked as stale because it has not had + recent activity. It will be closed if no further activity occurs. Thank you + for your contributions. + +# Comment to post when removing the stale label. +# unmarkComment: > +# Your comment here. + +# Comment to post when closing a stale Issue or Pull Request. +# closeComment: > +# Your comment here. + +# Limit the number of actions per hour, from 1-30. Default is 30 +limitPerRun: 30 + +# Limit to only `issues` or `pulls` +# only: issues + +# Optionally, specify configuration settings that are specific to just 'issues' or 'pulls': +# pulls: +# daysUntilStale: 30 +# markComment: > +# This pull request has been automatically marked as stale because it has not had +# recent activity. It will be closed if no further activity occurs. Thank you +# for your contributions. + +# issues: +# exemptLabels: +# - confirmed diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index d00984676..5a33fb8e4 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -50,8 +50,8 @@ jobs: - name: Render cloudformation id: render_cloudformation run: | - sed -i 's/ghcr.io\/openclarity\/vmclarity-backend:latest/ghcr.ioi\/openclarity\/vmclarity-backend:${{ github.ref_name }}/g' installation/aws/VmClarity.cfn - sed -i 's/ghcr.io\/openclarity\/vmclarity-cli:latest/ghcr.ioi\/openclarity\/vmclarity-cli:${{ github.ref_name }}/g' installation/aws/VmClarity.cfn + sed -i 's/ghcr.io\/openclarity\/vmclarity-backend:latest/ghcr.io\/openclarity\/vmclarity-backend:${{ github.ref_name }}/g' installation/aws/VmClarity.cfn + sed -i 's/ghcr.io\/openclarity\/vmclarity-cli:latest/ghcr.io\/openclarity\/vmclarity-cli:${{ github.ref_name }}/g' installation/aws/VmClarity.cfn - name: Set up Go uses: actions/setup-go@v3 diff --git a/README.md b/README.md index c94a211cc..4050c314e 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,6 @@ Software Bill Of Materials (SBOM) and vulnerabilities - [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)