Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: secureli 540 update documentation #560

Merged
merged 3 commits into from
Jun 5, 2024
Merged

docs: secureli 540 update documentation #560

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9542b73
Increased most headings one level
itoltz Jun 4, 2024
6b525df
Added documentation on pre-commit configuration
itoltz Jun 4, 2024
c962858
Fixed typos
itoltz Jun 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 56 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ seCureLI isn’t a magic tool that makes things secure because you have it. It e

Looking to contribute? Read our [CONTRIBUTING.md](https://github.com/slalombuild/secureli/blob/main/CONTRIBUTING.md)

# Installation
## Installation

## Homebrew
### Homebrew

To install seCureLI via homebrew, issue the following commands

Expand All @@ -26,17 +26,17 @@ brew tap slalombuild/secureli
brew install secureli
```

## pip (Package Installer for Python)
### pip (Package Installer for Python)

To install seCureLI via pip, issue the following commands

```commandline
pip install secureli
```

# Usage
## Usage

## Help
### Help

Once installed you can see the latest documentation for seCureLI by entering the following on a command prompt:

Expand Down Expand Up @@ -68,7 +68,7 @@ When invoking these commands, you can combine the short versions into a single f
% secureli init -ry
```

## Init
### 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 @@ -80,7 +80,7 @@ All you need to do is run:

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.

## Scan
### Scan

To manually trigger a scan, run:

Expand All @@ -90,47 +90,47 @@ To manually trigger a scan, run:

This will run through all hooks and custom scans, unless a `--specific-test` option is used. The default is to scan staged files only. To scan all files instead, use the `--mode all-files` option.

### PII Scan
#### PII Scan

seCureLI utilizes its own PII scan, rather than using an existing pre-commit hook. To exclude a line from being flagged by the PII scanner, you can use a `disable-pii-scan` marker in a comment to disable the scan for that line.

```
test_var = "some dummy data I don't want scanned" # disable-pii-scan
```

# Upgrade
## Upgrade

## Upgrading seCureLI via Homebrew
### Upgrading seCureLI via Homebrew

If you installed seCureLI using Homebrew, you can use the standard homebrew update command to pull down the latest formula.

```commandline
brew update
```

## Upgrading via pip
### 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
### 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.

```commandline
secureli update --latest
```

# Configuration
## Configuration

seCureLI is configurable via a .secureli.yaml file present in the root of your local repository.
### .secureli.yaml

## .secureli.yaml
seCureLI is configurable via a `.secureli.yaml` file present in the root of your local repository.

### top level
#### top level

| Key | Description |
|--------------------|--------------------------------------------------------------------------------------------------------------------|
Expand All @@ -140,38 +140,72 @@ seCureLI is configurable via a .secureli.yaml file present in the root of your l
| `pii_scanner` | Includes options for seCureLI's PII scanner |
| `telemetry` | Includes options for seCureLI telemetry/api logging |

### repo_files
#### 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
#### 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. |

### pii_scanner
#### pii_scanner

| Key | Description |
|----------------------|----------------------------------------------------------------|
| `ignored_extensions` | The extensions of files to ignore in addition to the defaults. |

### telemetry
#### telemetry

| Key | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_url` | The url endpoint to post telemetry logs to. This value is an alternative to setting the url as an environment variable. Note: The environment variable will precede this setting value |

## Using Observability Platform to Show Secret Detection Statistics
### pre-commit

[pre-commit](https://pre-commit.com/) is used for configuring pre-commit hooks. The configuration file is `.secureli/.pre-commit-config.yaml`, relative to the root of your repo. For details on modifying this file, see the pre-commit documentation on [configuring hooks](https://pre-commit.com/#pre-commit-configyaml---hooks).

#### Passing arguments to pre-commit hooks

Special care needs to be taken when passing arguments to pre-commit hooks in `.pre-commit-config.yaml`. In particular, if you're passing parameters which themselves take arguments, you must ensure that both the parameter and its arguments are separate items in the array.

Examples:

**BAD**

```yaml
- args:
- --exclude files *.md
```

This is an array with a single element, `["--exclude files *.md"]`. This probably won't work as you're expecting.

**GOOD**

```yaml
- args:
- --exclude files
- *.md
```

This is an array where the parameter and its argument are separate items; `["--exclude files", "*.md"]`

**ALSO GOOD**
```yaml
- args: ["--exclude-files", "*.md"]
```

### 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.
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
#### Steps for New Relic

- Assuming, seCureLI has been setup and installed, sign up to New Relic Log Platform https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/
- Retrieve API_KEY and API_ENDPOINT from New Relic. API_ENDPOINT for New Relic should be https://log-api.newrelic.com/log/v1
Expand Down
Loading