Merge pull request #1 from nightfallai/Alpha [semver:patch]

[semver:patch] initial pre-release

Author: alan20854

.circleci/config.yml

@@ -1,18 +1,79 @@
 version: 2.1
 
-jobs:
-  getting-started:
-    docker:
-      - image: circleci/node
-    steps:
-      - run:
-          name: Getting Started
-          command: |
-            echo "Your orb is now building on CircleCI"
-            echo "This is a temporary configuration file. Continue with the orb-init.sh script and follow the README.md to publish your orb."
+# add your orb below, to be used in integration tests (note: a @dev:alpha
+# release must exist.);
+orbs:
+  nightfall_code_scanner: nightfall/nightfall_code_scanner@<<pipeline.parameters.dev-orb-version>>
+  orb-tools: circleci/[email protected]
+
+# Pipeline parameters
+parameters:
+  # These pipeline parameters are required by the "trigger-integration-tests-workflow"
+  # job, by default.
+  run-integration-tests:
+    type: boolean
+    default: false
+  dev-orb-version:
+    type: string
+    default: "dev:alpha"
+
 workflows:
-  setup:
+  # This `lint-pack_validate_publish-dev` workflow will run on any commit.
+  lint_pack-validate_publish-dev:
+    unless: << pipeline.parameters.run-integration-tests >>
     jobs:
-      - getting-started
+      - orb-tools/lint
+      # pack your orb YAML files to a single orb.yml
+      # validate the orb.yml file to ensure it is well-formed
+      - orb-tools/pack:
+          requires:
+            - orb-tools/lint
+
+      # release dev version of orb, for testing & possible publishing.
+      # orb will be published as dev:alpha and dev:${CIRCLE_SHA1:0:7}.
+      # requires a CircleCI API token to be stored as CIRCLE_TOKEN (default)
+      # https://circleci.com/docs/2.0/managing-api-tokens
+      # store CIRCLE_TOKEN as a project env var or Contexts resource
+      # if using Contexts, add your context below
+      - orb-tools/publish-dev:
+          orb-name: nightfall/nightfall_code_scanner
+          requires:
+            - orb-tools/pack
+
+      # trigger an integration workflow to test the
+      # dev:${CIRCLE_SHA1:0:7} version of your orb
+      - orb-tools/trigger-integration-tests-workflow:
+          name: trigger-integration-dev
+          requires:
+            - orb-tools/publish-dev
+
+  # This `integration-tests_prod-release` workflow will only run
+  # when the run-integration-tests pipeline parameter is set to true.
+  # It is meant to be triggered by the "trigger-integration-tests-workflow"
+  # job, and run tests on <your orb>@dev:${CIRCLE_SHA1:0:7}.
+  integration-tests_prod-release:
+    when: << pipeline.parameters.run-integration-tests >>
+    jobs:
+      # your integration test jobs go here: essentially, run all your orb's
+      # jobs and commands to ensure they behave as expected. or, run other
+      # integration tests of your choosing
+
+      - nightfall_code_scanner/scan
 
+      # publish a semver version of the orb. relies on
+      # the commit subject containing the text "[semver:patch|minor|major|skip]"
+      # as that will determine whether a patch, minor or major
+      # version will be published or if publishing should
+      # be skipped.
+      # e.g. [semver:patch] will cause a patch version to be published.
+      - orb-tools/dev-promote-prod-from-commit-subject:
+          orb-name: nightfall/nightfall_code_scanner
 
+          add-pr-comment: false
+          fail-if-semver-not-indicated: true
+          publish-version-tag: false
+          requires:
+            - nightfall_code_scanner/scan
+          filters:
+            branches:
+              only: master

.gitignore

@@ -0,0 +1 @@
+.idea

.nightfalldlp/config.json

@@ -0,0 +1,9 @@
+{
+  "detectors": [
+    "API_KEY",
+    "CRYPTOGRAPHIC_KEY"
+  ],
+  "tokenExclusionList": [
+    "NF-gGpblN9cXW2ENcDBapUNaw3bPZMgcABs"
+  ]
+}

README.md

@@ -1,164 +1,136 @@
-# Orb Starter Kit [![CircleCI Build Status](https://circleci.com/gh/CircleCI-Public/orb-starter-kit.svg?style=shield "CircleCI Build Status")](https://circleci.com/gh/CircleCI-Public/orb-starter-kit) [![CircleCI Community](https://img.shields.io/badge/community-CircleCI%20Discuss-343434.svg)](https://discuss.circleci.com/c/ecosystem/orbs)
+# Nightfall DLP CircleCI Orb
+![nightfalldlp](https://nightfall.ai/wp-content/uploads/2020/08/nightfall-dark-logo-tm-e1597263930794.png)
+## [Nightfall](https://nightfall.ai) DLP Orb: A code review tool that protects you from committing sensitive information to your repositories.
 
-The Orb Starter Kit is a bash utility that makes creating your first orb a breeze!
+The Nightfall DLP CircleCI Orb scans your code commits for sensitive information - like credentials & secrets, PII, credit card numbers & more - and posts review comments to your code hosting service automatically. The Nightfall DLP CircleCI Orb is intended to be used as a part of your CI to simplify the development process, improve your security, and ensure you never accidentally leak secrets or other sensitive information via an accidental commit.
 
-**What are orbs?**
-Orbs are reusable [commands](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-commands), [executors](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-executors), and [jobs](https://circleci.com/docs/2.0/reusing-config/#jobs-defined-in-an-orb) (as well as [usage examples](https://github.com/CircleCI-Public/config-preview-sdk/blob/v2.1/docs/usage-examples.md))—snippets of CircleCI configuration—that can be shared across teams and projects. See [CircleCI Orbs](https://circleci.com/orbs), [Explore Orbs](https://circleci.com/orbs/registry), [Creating Orbs](https://circleci.com/docs/2.0/creating-orbs), and [Using Orbs](https://circleci.com/docs/2.0/using-orbs) for further information.
+## Example
+Here's an example of the Nightfall DLP CircleCI Orb providing feedback on a Pull Request:
 
-## What is in this kit?
+![nightfall-dlp-circle-orb-example](https://cdn.nightfall.ai/nightfall-code-scanner/circleci-github-comments.png)
 
-This kit includes three main components:
+Here's the CircleCI log output from the same run:
 
- * **Orb init script.**
-    * The Orb init script will auytomatically generate for you a new GitHub repository with all of the source code needed to get started developing your own orb, complete with automation pipeline
-* **Hello World template.**
-    * Within the [/src](https://github.com/CircleCI-Public/orb-starter-kit/tree/master/src) folder you can find find the destructured source of a simple "Hello World" orb. You can simply copy this code and begin hacking, or initialize it with our orb init script.
-* **Automated CI/CD Pipeline.**
-    * After you run the init script you will also be automatically given a development pipeline to test and update your orb on CircleCI.
-  * Automated Semver release process
-  * Automated Integration Testing
-  * No need to use CLI commands.
+![nightfall-dlp-circle-ui-example](https://cdn.nightfall.ai/nightfall-code-scanner/circleci-orb-workflow-ui.png)
 
+The orb runs when configured as a job in your CircleCI config:
 
+```yaml
+version: 2.1
 
-### Prerequisites
-
-Before getting started you will need the the following things:
-1. A CircleCI [account](https://circleci.com/signup/).
-2. Git installed and configured locally.
-3. A CircleCI [Personal API Token](https://circleci.com/docs/2.0/managing-api-tokens/#creating-a-personal-api-token) (Must be Org admin to claim a namespace and publish production Orbs)
-
+orbs:
+  nightfall_code_scanner: nightfall/[email protected]
 
+workflows:
+  test_scanner:
+    jobs:
+      - nightfall_code_scanner/scan:
+          event_before: << pipeline.git.base_revision >>
+```
 
 ## Usage
-
-### Getting started
-**1.** Clone this repo into a new directory with the name of your orb: 
-
-```
-git clone [email protected]:CircleCI-Public/orb-starter-kit.git My-Orb-Name
+**1. Get a Nightfall API key.**
+
+The Nightfall DLP Orb is powered by the Nightfall DLP API. Learn more and request access to a free API key **[here](https://nightfall.ai/api/)**. Alternatively, you can email **[[email protected]](mailto:[email protected])** to provision a free account.
+
+**2. Set up config file to specify detectors.**
+
+- Place a `.nightfalldlp/` directory within the root of your target repository, and inside it a `config.json` file in which you can configure your detectors (see `Detectors` section below for more information on Detectors)
+- See `Additional Configuration` section for more advanced configuration options
+- Below is a sample `.nightfalldlp/config.json` file:
+
+```json
+{
+  "detectors": [
+    "CREDIT_CARD_NUMBER",
+    "PHONE_NUMBER",
+    "API_KEY",
+    "CRYPTOGRAPHIC_KEY",
+    "RANDOMLY_GENERATED_TOKEN",
+    "US_SOCIAL_SECURITY_NUMBER",
+    "AMERICAN_BANKERS_CUSIP_ID",
+    "US_BANK_ROUTING_MICR",
+    "ICD9_CODE",
+    "ICD10_CODE",
+    "US_DRIVERS_LICENSE_NUMBER",
+    "US_PASSPORT",
+    "EMAIL_ADDRESS",
+    "IP_ADDRESS"
+  ]
+}
 ```
+**3. Set up a few environment variables.**     
+These variables should be made available to the Nightfall DLP orb by adding them to `Environment Variables` under `Project Settings` on the CircleCI console. Instructions [here](https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project):
 
-**2.** Create a new repository on GitHub with the same name. https://github.com/new
+- `NIGHTFALL_API_KEY`
+    - Get a free Nightfall DLP API Key by registering for an account with the [Nightfall API](https://nightfall.ai/api)
 
-**3.** Run the `orb-init.sh` script to begin.
+- `GITHUB_TOKEN` (Optional)
+    - Create a [Github Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `repo` scope
+    - This token is used to authenticate to Github to write Comments/Annotations to your Pull Requests and Pushes
+    - If not included, we will only log the finding messages to the CircleCI Workflow UI
 
-[![asciicast](https://asciinema.org/a/oSc3M8uJri4zfo616wOVbh1lO.svg)](https://asciinema.org/a/oSc3M8uJri4zfo616wOVbh1lO)
+- `EVENT_BEFORE`
+    - Make sure to include `event_before` as an argument with the value `<< pipeline.git.base_revision >>` in your circle config as shown in the example above
+    - This allows the orb to scan against the diff between the current commit sha and the most recent commit sha to trigger a workflow on push events
 
-The Orb Init script will automate the following tasks:
+- `BASE_BRANCH` (Optional)
+    - In the case that you want to scan your Pull Requests against a branch separate from `master`, include the `base_branch` argument with your branch's name in your circle config
+    - This will allow you to scan the diff between your Pull Request and `base_branch`
 
->  * Install and update the CircleCI CLI
->  * Request a CircleCI API token if none is currently set.
->  * Check to ensure git is installed and authenticated with GitHub.
->  * Connect your repository with the blank repo created in step 2.
->  * Create and switch to an "Alpha" branch
->  * Walk through creating a new orb via the CircleCI CLI
->  * Allow you to optionally enable advanced features.
->  * Create your customized config file
->  * Clean up - The script will remove itself from the repo for the next commit.
->  * Commit alpha branch with changes to GitHub.
+**4. Allow Uncertified Orbs**
+To use our orb, make sure to allow uncertified orbs in Organization Settings. Instructions are [here](https://circleci.com/docs/2.0/orbs-faq/#using-uncertified-orbs). At this time, CircleCI still requires allowing un-certified orbs to use orbs developed by CircleCI Partners.
+## Supported GitHub Events
+The Nightfall DLP CircleCI Orb can run in a Circle Workflow triggered by the following events:
 
-Your orb will now be available at `<your namespace>/<your orb>@dev:Alpha`
+- `PULL_REQUEST`
+- `PUSH`
 
-The script will end by giving you a link to the running automated pipeline on your CircleCI account which will be building a "Hello World" orb.
+The Nightfall DLP CircleCI Orb does not currently support forked repositories due to potential permissioning issues that may occur.
 
+## Detectors
+Each detector represents a type of information you want to search for in your code scans. A few examples of detectors Nightfall supports includes:
 
+- `API_KEY`: A freeform string used for user verification to access online program functions.
+- `CREDIT_CARD_NUMBER`: A 12 to 19 digit number used for payments and other monetary transactions.
+- `CRYPTOGRAPHIC_KEY`: A string of characters used by an encryption algorithm to generate seemingly random tokens.
+- `RANDOMLY_GENERATED_TOKEN`: A pseudo-random string generated by an encryption algorithm. This detector is more general than the API_KEY detector.
+- `US_SOCIAL_SECURITY_NUMBER`: A 9 digit numeric string often used as a unique identification number for United States citizens and residents.
+- Many more...
 
-**4.** Begin editing.
-> You may now edit the contents of the `/src` folder and commit your changes to the `Alpha` branch or any non-master branch.
+**Find a full list of supported detectors in the Nightfall API Documentation, after creating your account (per the instructions above).**
 
-**5.** Build and test!
-> All commits to non-master branches will automatically result in the creation of a development orb under that branch. The automated pipeline will then run your integration tests against that newly created dev orb.
+## Additional Configuration
 
-**6.** Publish!
-> Once ready to produce a new production version of your orb, you may merge your branch into the master branch to trigger the automated release process.
->
->**Recommended:** If you have enabled the `fail-if-semver-not-indicated` option, your commit message when merging to master _MUST_ include `[semver:patch|minor|major|skip]` to designate the release type.
->
-> You will need to manually publish the production version of your Orb for the initial version before the automated pipeline can update your production version later on. This is not needed on subsequent pushes. 
+You can add additional fields to your config to ignore tokens and files from being flagged, as well as specify which files to exclusively scan.
 
-Once the orb is complete, you will have two new Green workflows in your CircleCI account. The first one is for the initial setup and the second one will have produced a development version of your orb which contains a sample Command, Executor, and Job. 
+### Token Exclusion
 
+To ignore specific tokens from being flagged, you can add the `tokenExclusionList` field to your nightfalldlp config. The `tokenExclusionList` is a list of strings, and it mutes findings that match any of the given regex patterns.
 
-### Writing your orb
-This orb provides a basic directory/file structure for a decomposed orb (where commands, jobs, examples, and executors each live in their own YAML file). Create each of your commands, jobs, examples, and executors within the requisite folders in the `src` directory.
+Here's an example use case:
 
-Following are some resources to help you build and test your orb:
+```tokenExclusionList: ["NF-gGpblN9cXW2ENcDBapUNaw3bPZMgcABs", "^127\\."]```
 
-- [Intro to authoring orbs](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration)
-- [Orb Best Practices](https://circleci.com/docs/2.0/orbs-best-practices/#orb-best-practices-guidelines)
-- [How to make an easy and valuable open source contribution with CircleCI orbs](https://circleci.com/blog/how-to-make-an-easy-and-valuable-open-source-contribution-with-circleci-orbs/)
+In the example above, findings with the API token `NF-gGpblN9cXW2ENcDBapUNaw3bPZMgcABs` as well as local IP addresses starting with `127.` would not be reported. For more information on how we match tokens, take a look at [regexp](https://golang.org/pkg/regexp/).
 
+### File Inclusion & Exclusion
 
-### Permissions
+To omit files from being scanned, you can add the `fileExclusionList` field to your nightfalldlp config. In addition, to only scan specific files, add the `fileInclusionList` to the config.
 
-Explanation of all permissions required for the script.
-
-* **sudo** - The CircleCI CLI Update command will request sudo permissions to update.
-
-### Preview
+Here's an example use case:
+```
+    fileExclusionList: ["*/tests/*"],
+    fileInclusionList: ["*.go", "*.json"]
+```
+In the example, we are ignoring all file paths with a `tests` subdirectory, and only scanning on `go` and `json` files.
+Note: we are using [gobwas/glob](https://github.com/gobwas/glob) to match file path patterns. Unlike the token regex matching, file paths must be completely matched by the given pattern. e.g. If `tests` is a subdirectory, it will not be matched by `tests/*`, which is only a partial match.
 
-<details>
-<Summary>Preview "Hello-World" Orb produced by this repo by default.</Summary>
+## [Nightfall DLP API](https://nightfall.ai/api)
+With the Nightfall API, you can inspect & classify your data, wherever it lives. Programmatically get structured results from Nightfall's deep learning-based detectors for things like credit card numbers, API keys, and more. Scan data easily in your own third-party apps, internal apps, and data silos. Leverage these classifications in your own workflows - for example, saving them to a data warehouse or pushing them to a SIEM. Request access & learn more **[here](https://nightfall.ai/api/)**.
 
-```yaml
-commands:
-  greet:
-    description: |
-      Replace this text with a description for this command. # What will this command do? # Descriptions should be short, simple, and clear.
-    parameters:
-      greeting:
-        default: Hello
-        description: Select a proper greeting
-        type: string
-    steps:
-    - run:
-        command: echo << parameters.greeting >> world
-        name: Hello World
-description: |
-  Sample orb description # What will your orb allow users to do? # Descriptions should be short, simple, and clear.
-examples:
-  example:
-    description: |
-      Sample example description. # What will this example document? # Descriptions should be short, simple, and clear.
-    usage:
-      jobs:
-        build:
-          machine: true
-          steps:
-          - foo/hello:
-              username: Anna
-      orbs:
-        foo: bar/[email protected]
-      version: 2.1
-executors:
-  default:
-    description: |
-      This is a sample executor using Docker and Node. # What is this executor? # Descriptions should be short, simple, and clear.
-    docker:
-    - image: circleci/node:<<parameters.tag>>
-    parameters:
-      tag:
-        default: latest
-        description: |
-          Pick a specific circleci/node image variant: https://hub.docker.com/r/circleci/node/tags
-        type: string
-jobs:
-  hello:
-    description: |
-      # What will this job do? # Descriptions should be short, simple, and clear.
-    executor: default
-    parameters:
-      greeting:
-        default: Hello
-        description: Select a proper greeting
-        type: string
-    steps:
-    - greet:
-        greeting: << parameters.greeting >>
-orbs:
-  hello: circleci/[email protected]
-version: 2.1
-```
+## Versioning
+The Nightfall DLP CircleCI Orb issues releases using semantic versioning.
 
-</details>
+## Support
+For help, please email us at **[[email protected]](mailto:[email protected])**.