Skip to content

Commit

Permalink
chore: readme and contributing guide updates (#418)
Browse files Browse the repository at this point in the history 
secureli-396

closes #396 

General updates and clean up to readme and contributing guides.


## Changes
* Updated README.md
* Updated CONTRIBUTING.md

## Testing
N/A

## Clean Code Checklist
<!-- This is here to support you. Some/most checkboxes may not apply to
your change -->
- [ ] Meets acceptance criteria for issue
- [ ] New logic is covered with automated tests
- [ ] Appropriate exception handling added
- [ ] Thoughtful logging included
- [ ] Documentation is updated
- [ ] Follow-up work is documented in TODOs
- [ ] TODOs have a ticket associated with them
- [ ] No commented-out code included


<!--
Github-flavored markdown reference:
https://docs.github.com/en/get-started/writing-on-github
-->

Co-authored-by: Jordan Heffernan <44213782+JordoHeffernan@users.noreply.github.com>
  • Loading branch information
@kevin-orlando @JordoHeffernan
kevin-orlando and JordoHeffernan committed Feb 9, 2024
1 parent 1d67736 commit 2ab23c1
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 29 deletions.
46 changes: 31 additions & 15 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,18 @@ This project requires a single approval

We use `python-semantic-versioning` for automated versioning on merges to main. In order for this to work, your PR title must contain the type of change followed by a colon followed by your title.

Like this:
Valid prefixes are: `chore, style, test, feat, fix, docs, or ci`

Example:
`chore: my PR title`

Valid prefixes are defined in the [angular documentation](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
Refer to the [angular documentation](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit) for more information on title prefixes

| :memo: | Note |
|---------------|:-----------|
| :memo: | Note |
| ------ | :--- |

> _Use "feat" to cut a minor release automatically. "fix", "perf", or "chore(release)" will create a patch release.
Note that "build", "chore", "ci", "docs", "style", "refactor", and "test" do not create a release._
> Note that "build", "chore", "ci", "docs", "style", "refactor", and "test" do not create a release._
# Environment Requirements

Expand All @@ -40,11 +42,12 @@ seCureLI has Slalom-maintained templates for security management of the followin
This repo was started against Python 3.9.9, which released 11/15/2021. Security support will last until 10/05/2025. Newer versions should be fine, older versions will likely not work.

## Setup macOS

As of June 9, 2023, this repo is being built on and tested against macOS 13.4 Ventura.

_Note about the C Compiler: Certain dependencies are implemented as C extensions. Under certain circumstances, you may need to compile the package from sources on your machine. You’ll need a C compiler and Python header files, such as Xcode and Xcode’s command line tools for the Mac, if this is the case. Generally you’ll be guided through this process as you attempt to resolve dependencies (see `poetry install` below)._

___Do no setup for this requirement__ unless prompted to do so, and then follow the instructions given._
**Do no setup for this requirement** unless prompted to do so, and then follow the instructions given.

- Install Homebrew if needed: https://brew.sh
- Install python `brew install python`
Expand All @@ -65,6 +68,7 @@ ___Do no setup for this requirement__ unless prompted to do so, and then follow
- Jump to [Setup (all Operating Systems)](#Setup-all-Operating-Systems)

## Setup Windows™

Windows™ contributing setup will be coming soon.

## Setup Linux
Expand All @@ -80,7 +84,9 @@ As of June 9, 2023, this repo is being built on and tested against Ubuntu Jammy
- Install [Docker & Docker buildx](https://docs.docker.com/engine/install/)

# Setup (all Operating Systems)

- Install BATS (Bash Automated Testing System)

- `cd $HOME`
- `git clone https://github.com/bats-core/bats-core.git`
- `sudo ./bats-core/install.sh /usr/local`
Expand All @@ -89,33 +95,36 @@ As of June 9, 2023, this repo is being built on and tested against Ubuntu Jammy
- Add `export BATS_LIBS_ROOT="/usr/local/lib"` to your shell's configuration file (e.x. ~/.bashrc)
- Restart your terminal


- Clone the seCureLI repo

- `git clone https://github.com/slalombuild/secureli.git`
- `cd secureli`


- Activate a virtual environment using Poetry

- `poetry shell`
- This will activate a new virtual environment, and PyCharm should automatically pick this up.
- To leave this virtual environment, use `exit`, not `deactivate`


- Install your dependencies with Poetry
- `poetry install`

- `poetry install`

- Run the tests and calculate code coverage

- `poe test`
- Open the `htmlcov/index.html` file to view your coverage report


- Try it out!
- With the virtual environment still activated, and having installed all dependencies (i.e. `poetry shell && poetry install`), run `secureli` and check out the Usage instructions
- After the first run, you can run end-to-end BATS tests with `poe e2e`

# Development with PyCharm

Optionally use PyCharm to run and debug changes during developement

## Setup

# PyCharm
- Install [PyCharm Community Edition](https://www.jetbrains.com/pycharm/download/#section=mac)
- Launch PyCharm and create a new sample project
- Use the Tools menu and select `Create Command-line Launcher...`
Expand Down Expand Up @@ -146,7 +155,7 @@ As of June 9, 2023, this repo is being built on and tested against Ubuntu Jammy
- If it does not say “Init”, select it in the dropdown
- This should display terminal output within PyCharm that looks like the following:

```jsx
```
/secureli-LF8LGRWE-py3.9/bin/python secureli/main.py init
seCureLI has not been setup yet. Initialize seCureLI now? [Y/n]:
```
Expand Down Expand Up @@ -184,12 +193,17 @@ Already installed for Python language and up to date
- Parameters: `build`
- Test each of these configurations and see that the expected “not yet implemented” message is shown

# Development with VS Code

Follow the python [set up guide](https://code.visualstudio.com/docs/python/python-quick-start) for VS Code.

# Building seCureLI Docker Containers behind a corporate proxy

If you receive SSL/TLS untrusted certificate errors when building the Docker images,
chances are your organization's digital security team is using a proxy to monitor your encrypted internet usage. To build
the seCureLI Docker images you will need to inject your organizations self-signed root CA certificate into the images
at build time. To do this, simply place the root certificate (*.crt format) into the `ca-certificates` directory of this
repository. Everything in the ca-certificates directory will be picked up and trusted by the images built.
at build time. To do this, simply place the root certificate (\*.crt format) into the `ca-certificates` directory of this
repository. Everything in the ca-certificates directory will be picked up and trusted by the images built.

# seCureLI Architecture

Expand Down Expand Up @@ -278,7 +292,9 @@ Current Dockerfiles
- Checks out the public pip repo, inits secureli into the repo and runs a scan

# Contributors

A special thanks to everyone that has contributed to seCureLI so far:

- Jon Allegre
- Dan Arnold
- Nava Atluri
Expand Down
31 changes: 17 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,22 +41,23 @@ pip install secureli
Once installed you can see the latest documentation for seCureLI by entering the following on a command prompt:

```bash
% secureli --help
$ secureli --help
```

You will see a list of commands and descriptions of each. You can also pull up documentation for each command with the same pattern. For example:

```bash
% secureli init --help
$ secureli init --help

Usage: secureli init [OPTIONS]

Detect languages and initialize pre-commit hooks and linters for the project

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────╮
│ --reset -r Disregard the installed configuration, if any, and treat as a new install │
│ --yes -y Say 'yes' to every prompt automatically without input │
│ --help Show this message and exit. │
│ --reset -r Disregard the installed configuration, if any, and treat as a new install │
│ --yes -y Say 'yes' to every prompt automatically without input │
│ --directory .,-d PATH Run secureli against a specific directory [default: .]
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯
```
Expand All @@ -66,6 +67,7 @@ When invoking these commands, you can combine the short versions into a single f
% secureli init --reset --yes
% secureli init -ry
```
## Init
After seCureLI is installed, you can use it to configure your local git repository with a set of pre-commit hooks appropriate for your repo, based on the languages found in your repo's source code files.
Expand All @@ -76,7 +78,7 @@ All you need to do is run:
% secureli init
```
Running `secureli init` will allow seCureLI to detect the languages in your repo, install pre-commit, install all the appropriate pre-commit hooks for your local repo, and run a scan for secrets in your local repo.
Running `secureli init` will allow seCureLI to detect the languages in your repo, install pre-commit, install all the appropriate pre-commit hooks for your local repo, run a scan for secrets in your local repo, and update the installed hooks.
# Upgrade
Expand All @@ -87,13 +89,15 @@ If you installed seCureLI using Homebrew, you can use the standard homebrew upda
```commandline
brew update
```
## Upgrading via pip
If you installed seCureLI using pip, you can use the following command to upgrade to the latest version of seCureLI.
```commandline
pip install --upgrade secureli
```
## Upgrading pre-commit hooks for repo
In order to upgrade to the latest released version of each pre-commit hook configured for your repo, use the following command.
Expand All @@ -111,29 +115,28 @@ seCureLI is configurable via a .secureli.yaml file present in the root of your l
### top level
| Key | Description |
|--------------------|--------------------------------------------------------------------------------------------------------------------|
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `repo_files` | Affects how seCureLI will interpret the repository, both for language analysis and as it executes various linters. |
| `echo` | Adjusts how seCureLI will print information to the user. |
| `language_support` | Affects seCureLI's language analysis and support phase. |
### repo_files
| Key | Description |
|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_file_size` | A number in bytes. Files over this size will not be considered during language analysis, for speed purposes. Default: 100000 |
| `ignored_file_extensions` | Which file extensions not to consider during language analysis. |
| `exclude_file_patterns` | Which file patterns to ignore during language analysis and code analysis execution. Use a typical file pattern you might find in a .gitignore file, such as `*.py` or `tests/`. Certain patterns you will have to wrap in double-quotes for the entry to be valid YAML. |
### echo
| Key | Description |
|---------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `level` | The log level to display to the user. Defaults to ERROR, which includes `error` and `print` messages, without including warnings or info messages. |
| Key | Description |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `level` | The log level to display to the user. Defaults to ERROR, which includes `error` and `print` messages. Available log levels are DEBUG, INFO, WARN, and ERROR |
## Using Observability Platform to Show Secret Detection Statistics
seCureLI can send secret detection events to an observability platform, such as New Relic. Other platforms may also work, but have not been tested.
seCureLI can send secret detection events to an observability platform, such as New Relic. Other platforms may also work, but have not been tested.
Should you need seCureLI to work with other platforms, please create a new issue in github, or contribute to the open source project.
### Steps for New Relic
Expand All @@ -150,7 +153,7 @@ FROM Log Select sum(failure_count_details.detect_secrets) as 'Caught Secret Coun
## License
Copyright 2023 Slalom, Inc.
Copyright 2024 Slalom, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down

0 comments on commit 2ab23c1

Please sign in to comment.