Skip to content

Commit

Permalink
Merge branch 'master' into string-array-config
Browse files Browse the repository at this point in the history
  • Loading branch information
@jossef
jossef authored Sep 10, 2023
2 parents a1b5e2c + 135b2d3 commit da68062
Showing 1 changed file with 151 additions and 12 deletions.
163 changes: 151 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

# Installation

## Download Precompiled Binaries
### Download Precompiled Binaries

2ms precompiled binaries for amd64 architecture are attached as assets in our [releases page](https://github.com/Checkmarx/2ms/releases)

Expand All @@ -18,16 +18,22 @@
- [Download for Linux](https://github.com/checkmarx/2ms/releases/latest/download/linux-amd64.zip)
- [Other](https://github.com/Checkmarx/2ms/releases)

### Install Globally
#### Install Globally

You may place the compiled binary on your path. On Linux for example you can place `2ms` binary in `/usr/local/bin/`
You may place the compiled binary on your path. On Linux for example you can place `2ms` binary in `/usr/local/bin/` or create a symbolic link. For example:

```
chmod +x 2ms
sudo cp 2ms /usr/local/bin/
cd /opt
mkdir 2ms
cd 2ms
wget https://github.com/checkmarx/2ms/releases/latest/download/linux-amd64.zip
unzip linux-amd64.zip
sudo ln -s /opt/2ms/2ms /usr/local/bin/2ms
```

## Compiling from source
[![asciicast](https://asciinema.org/a/zkgwRn5fF7JG8uUG3MGJy6UGT.svg)](https://asciinema.org/a/zkgwRn5fF7JG8uUG3MGJy6UGT)

### Compiling from source

If you wish to compile the project from its source use the following commands

Expand All @@ -38,7 +44,7 @@ go build -o dist/2ms main.go
./dist/2ms
```

## Docker Container
### Run From Docker Container

We publish container image releases of `2ms` to [checkmarx/2ms](https://hub.docker.com/r/checkmarx/2ms) . To run `2ms` from a docker container use the following command:

Expand All @@ -54,11 +60,43 @@ docker run -v /home/user/workspace/git-repo:/repo checkmarx/2ms git /repo

- For `git` command, you have to mount your git repository to `/repo` inside the container

# Usage
### GitHub Actions

To use in GitHub actions, make sure you tell `actions/checkout` step to go full history depth by setting `fetch-depth: 0`

```yaml
name: Pipeline Example With 2MS

on:
pull_request:
workflow_dispatch:
push:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
with:
# Required for 2ms to have visibility to all commit history
fetch-depth: 0

# ...

- name: Run 2ms Scan
run: docker run -v $(pwd):/repo checkmarx/2ms:2.8.1 git /repo
```
- In this example we've pinned the version to `2.8.1`. Make sure to check out if there's a newer version
- 💡 Take a look at [2ms GitHub Actions pipeline](https://github.com/Checkmarx/2ms/blob/master/.github/workflows/release.yml) as 2ms scans itself using 2ms.

# Command Line Interface

We've built `2ms` command line interface to be as self-descriptive as possible. This is the help message that you will see if you executed `2ms` without args:

<!-- command-line:start -->

```
2ms Secrets Detection: A tool to detect secrets in public websites and communication services.

Expand Down Expand Up @@ -92,6 +130,26 @@ Flags:

Use "2ms [command] --help" for more information about a command.
```

Check failure on line 132 in README.md

View workflow job for this annotation

GitHub Actions / README should be updated

Outdated README 

README.md is outdated, please run ./.ci/update-readme.sh
## Custom Regex Rules
You may specify one or more custom regex rules with the optional argument `--regex`. The value provided will be parsed as a regular expression and will be matched against the target items.
my-file.txt
```
password=1234567
username=admin
```
```
2ms filesystem --path . --regex username= --regex password=
```
[![asciicast](https://asciinema.org/a/607198.svg)](https://asciinema.org/a/607198)
<!-- command-line:end -->
## Plugins
Expand Down Expand Up @@ -122,20 +180,48 @@ For example:
- 💡 [The `secrets` Confluence site](https://checkmarx.atlassian.net/wiki/spaces/secrets) purposely created with plain example secrets as a test subject for this demo
[![asciicast](https://asciinema.org/a/607179.svg)](https://asciinema.org/a/607179)
### Paligo
`<TBD Add Reference>`
Scans [Paligo](https://paligo.net/) content management system instance.
| Flag | Value | Default | Description |
|--------------|--------|---------------------------------|--------------------------------------------------|
| `--instance` | string | - | Instance name |
| `--token` | string | - | API token for authentication |
| `--username` | string | - | Confluence user name or email for authentication |
| `--folder` | string | scanning all instance's folders | Folder ID |
| `--auth` | string | - | Base64 auth header encoded username:password |
### Discord
`<TBD Add Reference>`
Scans [Discord](https://discord.com/) chat application history.
| Flag | Value | Default | Description |
|--------------------|----------|----------------------------------|--------------------------------------------------------------------------------------------------------|
| `--token` | string | - | Discord token |
| `--channel` | strings | all channels will be scanned | Discord channel IDs to scan |
| `--messages-count` | int | 0 = all messages will be scanned | Confluence user name or email for authentication |
| `--duration` | duration | 14 days | The time interval to scan from the current time. For example, 24h for 24 hours or 336h0m0s for 14 days |
| `--server` | strings | - | Discord servers IDs to scan |
### Slack
`<TBD Add Reference>`
Scans [Slack](https://slack.com/) chat application history.
| Flag | Value | Default | Description |
|--------------------|----------|----------------------------------|--------------------------------------------------------------------------------------------------------|
| `--token` | string | - | Slack token |
| `--channel` | strings | all channels will be scanned | Slack channel IDs to scan |
| `--messages-count` | int | 0 = all messages will be scanned | Confluence user name or email for authentication |
| `--duration` | duration | 14 days | The time interval to scan from the current time. For example, 24h for 24 hours or 336h0m0s for 14 days |
| `--team` | string | - | Slack team name or ID |
### Git Repository
Scans a local git repository
```
2ms git <Git Repo Local Path> [flags]
```
Expand All @@ -155,7 +241,60 @@ cd my-repo
### Local Directory
`<TBD Add Reference>`
Scans a local repository
```
2ms filesystem --path PATH [flags]
```
| Flag | Value | Default | Description |
|--------------------|---------|---------|--------------------------------------------------------|
| `--path` | string | - | Local directory path |
| `--project-name` | string | - | Project name to differentiate between filesystem scans |
| `--ignore-pattern` | strings | - | Patterns to ignore |
## Configuration File
You can pass `--config [path to config file]` argument to specify a configuration file. The configuration file format can be in YAML or JSON.
```yaml
log-level: info
regex:
- password\=
report-path:
- ./report.yaml
- ./report.json
- ./report.sarif
paligo:
instance: your-instance
username: your-username
```

### Hybrid Configuration Mode

You may pass a combination of command line arguments **and** a configuration file, the result is going to merge the values from the file and the explicit arguments

`.2ms.yml` config file:

```yaml
ignore-result:
- b0a735b7b0a2bc6fb1cd69824a9afd26f0f7ebc8
- 51c76691792d9f6efe8af1c89c678386349f48a9
- 81318f7350a4c42987d78c99eacba2c5028636cc
- 8ea22c1e010836b9b0ee84e14609b574c9965c3c
```
command, `--space` is provided outside of config file:

```yaml
docker run -v $(pwd)/.2ms.yml:/app/.2ms.yml checkmarx/2ms confluence --url https://checkmarx.atlassian.net/wiki --spaces secrets --config /app/.2ms.yml
```

[![asciicast](https://asciinema.org/a/n8RHL4v6vI87uiUPZ9I7CgfYy.svg)](https://asciinema.org/a/n8RHL4v6vI87uiUPZ9I7CgfYy)

## Contributing

Expand Down

0 comments on commit da68062

Please sign in to comment.