Skip to content

Latest commit

 

History

History
101 lines (70 loc) · 4.77 KB

README.md

File metadata and controls

101 lines (70 loc) · 4.77 KB

Polar (OSS)

Copyright 2024 Carnegie Mellon University.

NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING INSTITUTE MATERIAL IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT.

Licensed under a MIT-style license, please see license.txt or contact permission@sei.cmu.edu for full terms.

[DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution. Please see Copyright notice for non-US Government use and distribution.

This Software includes and/or makes use of Third-Party Software each subject to its own license.

DM24-0470

Getting Started in the Polar Workspace

This directory contains several of the agents that compose the polar framework.

See the README files for each component for details.

Requirements

Operating System

MacOS Monterrey or newer or modern Linux

Instructions written and tested on an Intel Mac running MacOS Sonoma (14.5) and Ubuntu 22.04 (LTS) on an Amazon EC2 instance (t3.2xlarge).

Hardware

  • Multi-core CPU
  • At least 8GB of RAM
  • 25GB Free Storage

Software

A reminder - you don't have to install everything yourself

This flake will give you a containerized development environment with everything needed to start development.

Building

The workspace leverages Nix, Nix flakes, and the Crane library to streamline the project's continuous integration and delivery practices. One will need to ensure the nix package manager is installed with flakes enabled to take advantage of it.

NOTE: This project specifcally targets x86-64-linux platforms exclusively, so we reccomend users either that they use a system or containerized environment that fits this. MacOS users in particular may be interested in running the darwin-builder locally as a virtual machine and delegating builds to it over ssh. Otherwise, using some other machine with nix installed as a remote buider.

Running nix build from this directory will build all binaries specified by the Cargo.toml in this workspace by default.

If desired for testing, you can also use it to generate a self-signed client/server pair of certificates to facilitate the mTLS communications.

It is possible to build individual or multiple components at a time. Below are some examples of how.

# Generate TLS Certificates, you need this to get run the broker and any agents.
nix build .#tlsCerts -o certs

# build the entire cargo workspace
nix build -o polar

# Build only the observer or consumer agents
nix build .#polarPkgs.gitlabObserver.observer -o gitlab-observer
nix build .#polarPkgs.gitlabConsumer.consumer -o gitlab-consumer

Manual Steps

mTlS Setup

If you can't or won't use nix, SSL files will need to be generated for the agents manually, or, you will have to provide your own certificates. This project formally used rabbitmq as it's message broker and one of its tools tls-gen, to create our self signed certificate files for testing. Developers can do so as well.

There are instructions in the basic directory in that repo for how to do so, but here are the basics:

  1. Clone the repo and change into the basic directory
  2. Run make CN=polar to generate the basic certificates.
  3. Copy the contents of the created results directory to somewhere the they can be easily found. For example, `
    1. mkdir $PROJECT_ROOT/conf/gitlab_compose/ssl
    2. cp results/* $PROJECT_ROOT/conf/certs

Running Unit and Integration Tests

In order to run unit and integration tests, you can use the following commands:

NOTE: Some integration tests leverage testcontainers, so a container runtime such as Docker or Podman must be present and configured on the host. If using Podman, consider setting the DOCKER_HOST environment variable to point to the Podman socket.

cargo test --package polar -- --nocapture