You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
35
35
36
-
**2. Set up config file to specify detectors.**
36
+
**2. Set up config file to specify condition set.**
37
37
38
-
- 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)
38
+
- Place a `.nightfalldlp/` directory within the root of your target repository, and inside it a `config.json` file in which you can configure your condition set (see the `Conditions` section below for more information)
39
39
- See `Additional Configuration` section for more advanced configuration options
40
-
- Below is a sample `.nightfalldlp/config.json` file:
40
+
- In the absence of a Nightfall config file, the scan will be performed with a default condition set containing the `API_KEY` and `CRYPTOGRAPHIC_KEY` detectors will be used.
41
41
42
-
```json
43
-
{
44
-
"detectors": [
45
-
"CREDIT_CARD_NUMBER",
46
-
"PHONE_NUMBER",
47
-
"API_KEY",
48
-
"CRYPTOGRAPHIC_KEY",
49
-
"RANDOMLY_GENERATED_TOKEN",
50
-
"US_SOCIAL_SECURITY_NUMBER",
51
-
"AMERICAN_BANKERS_CUSIP_ID",
52
-
"US_BANK_ROUTING_MICR",
53
-
"ICD9_CODE",
54
-
"ICD10_CODE",
55
-
"US_DRIVERS_LICENSE_NUMBER",
56
-
"US_PASSPORT",
57
-
"EMAIL_ADDRESS",
58
-
"IP_ADDRESS"
59
-
]
60
-
}
61
-
```
62
42
**3. Set up a few environment variables.**
63
43
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):
64
44
@@ -80,6 +60,7 @@ These variables should be made available to the Nightfall DLP orb by adding them
80
60
81
61
**4. Allow Uncertified Orbs**
82
62
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.
63
+
83
64
## Supported GitHub Events
84
65
The Nightfall DLP CircleCI Orb can run in a Circle Workflow triggered by the following events:
85
66
@@ -88,21 +69,190 @@ The Nightfall DLP CircleCI Orb can run in a Circle Workflow triggered by the fol
88
69
89
70
The Nightfall DLP CircleCI Orb does not currently support forked repositories due to potential permissioning issues that may occur.
90
71
91
-
## Detectors
92
-
Each detector represents a type of information you want to search for in your code scans. A few examples of detectors Nightfall supports includes:
72
+
## Nightfalldlp Config File
73
+
74
+
The .nightfalldlp/config.json file is used as a centralized config file to control what conditions/detectors to scan with and what content you want to scan for in your pull requests. It includes the following adjustable fields to fit your needs.
75
+
76
+
### ConditionSetUUID
77
+
78
+
A condition set uuid is a unique identifier of a condition set, which can be created via [app.nightfall.ai](app.nightfall.ai).
79
+
Once defined, you can simply input the uuid in your config file, e.g.
Note: by default, if both conditionSetUUID and conditions are specified, only the conditionSetUUID will be used.
86
+
87
+
### Conditions
88
+
89
+
Conditions are a list of conditions specified inline. Each condition contains a nested detector object as well as two additional parameters: minNumFindings and minConfidence.
93
90
94
-
- `API_KEY`: A freeform string used for user verification to access online program functions.
95
-
- `CREDIT_CARD_NUMBER`: A 12 to 19 digit number used for payments and other monetary transactions.
96
-
- `CRYPTOGRAPHIC_KEY`: A string of characters used by an encryption algorithm to generate seemingly random tokens.
97
-
- `RANDOMLY_GENERATED_TOKEN`: A pseudo-random string generated by an encryption algorithm. This detector is more general than the API_KEY detector.
98
-
- `US_SOCIAL_SECURITY_NUMBER`: A 9 digit numeric string often used as a unique identification number for United States citizens and residents.
99
-
- Many more...
91
+
```json
92
+
{
93
+
"conditions": [
94
+
{
95
+
"minNumFindings": 1,
96
+
"minConfidence": "POSSIBLE",
97
+
"detector": {}
98
+
}
99
+
]
100
+
}
101
+
```
100
102
101
-
**Find a full list of supported detectors in the Nightfall API Documentation, after creating your account (per the instructions above).**
103
+
minNumFindings specifies the minimal number of findings required to return for one request, e.g. if you set minNumFindings to be 2, and only 1 finding within the request payload related to that detector, that finding then will be filtered out from the response.
104
+
105
+
minConfidence specifies the minimal threshold to trigger a potential finding to be captured. We have five levels of confidence from least sensitive to most sensitive:
106
+
107
+
- VERY_LIKELY
108
+
- LIKELY
109
+
- POSSIBLE
110
+
- UNLIKELY
111
+
- VERY_UNLIKELY
112
+
113
+
### Detector
114
+
115
+
A detector is either a prebuilt Nightfall detector or custom regex or wordlist detector that you can create. This is specified by the detectorType field.
116
+
117
+
- nightfall prebuilt detector
118
+
119
+
```json
120
+
{
121
+
"detector": {
122
+
"detectorType": "NIGHTFALL_DETECTOR",
123
+
"nightfallDetector": "API_KEY",
124
+
"displayName": "apiKeyDetector"
125
+
}
126
+
}
127
+
```
128
+
129
+
Within detector struct
130
+
131
+
- First specify detectorType as NIGHTFALL_DETECTOR
132
+
- Pick the nightfall detector you want from the list
133
+
- API_KEY
134
+
- CRYPTOGRAPHIC_KEY
135
+
- RANDOMLY_GENERATED_TOKEN
136
+
- CREDIT_CARD_NUMBER
137
+
- US_SOCIAL_SECURITY_NUMBER
138
+
- AMERICAN_BANKERS_CUSIP_ID
139
+
- US_BANK_ROUTING_MICR
140
+
- ICD9_CODE
141
+
- ICD10_CODE
142
+
- US_DRIVERS_LICENSE_NUMBER
143
+
- US_PASSPORT
144
+
- PHONE_NUMBER
145
+
- IP_ADDRESS
146
+
- EMAIL_ADDRESS
147
+
- Put a display name for your detector, as this will be attached on your findings
148
+
149
+
- customized regex
150
+
151
+
We also support customized regex as a detector, which are defined as followed:
152
+
153
+
```json
154
+
{
155
+
"detector": {
156
+
"detectorType": "REGEX",
157
+
"regex": {
158
+
"pattern": "coupon:\\d{4,}",
159
+
"isCaseSensitive": false
160
+
},
161
+
"displayName": "simpleRegexCouponDetector"
162
+
}
163
+
}
164
+
```
165
+
166
+
- word list
167
+
168
+
Word list detectors look for words you specify in its list. Example below:
169
+
170
+
```json
171
+
{
172
+
"detector": {
173
+
"detectorType": "WORD_LIST",
174
+
"wordList": {
175
+
"values": ["key", "credential"],
176
+
"isCaseSensitive": false
177
+
},
178
+
"displayName": "simpleWordListKeyDetector"
179
+
}
180
+
}
181
+
```
182
+
183
+
- [Extra Parameters Within Detector]
184
+
185
+
Aside from specifying which detector to use for a condition, you can also specify some additional rules to attach. They are contextRules and exclusionRules.
186
+
187
+
- contextRules
188
+
A context rule evaluates the surrounding context(pre/post chars) of a finding and adjusts the finding's confidence if the input context rule pattern exists.
189
+
190
+
Example:
191
+
192
+
```json
193
+
{
194
+
"detector": {
195
+
// ...... other detector fields
196
+
"contextRules": [
197
+
{
198
+
"regex": {
199
+
"pattern": "my cc",
200
+
"isCaseSensitive": true
201
+
},
202
+
"proximity": {
203
+
"windowBefore": 30,
204
+
"windowAfter": 30
205
+
},
206
+
"confidenceAdjustment": {
207
+
"fixedConfidence": "VERY_LIKELY"
208
+
}
209
+
}
210
+
]
211
+
}
212
+
}
213
+
```
214
+
215
+
- regex field specifies a regex to trigger
216
+
- proximity is defined as the number pre|post chars surrounding the finding to conduct the search
217
+
- confidenceAdjustment is the confidence level to adjust the finding to upon existence of the input context
218
+
219
+
As an example, say we have the following line of text in a file `my cc number: 4242-4242-4242-4242`, and `4242-4242-4242-4242` is detected as a credit card number with confidence of POSSIBLE. If we had the context rule above, the confidence level of this finding will be bumped up to `VERY_LIKELY` because the characters preceding the finding, `my cc`, match the regex.
220
+
221
+
- exclusionRules
222
+
Exclusion rules on individual conditions are used to mute findings related to that condition's detector.
223
+
224
+
Example:
225
+
226
+
```json
227
+
{
228
+
"detector": {
229
+
// ...... other detector fields
230
+
"exclusionRules": [
231
+
{
232
+
"matchType": "PARTIAL",
233
+
"exclusionType": "REGEX",
234
+
// specify one of these values based on the type specified above
235
+
"regex": {
236
+
"pattern": "4242-4242-\\d{4}-\\d{4}",
237
+
"isCaseSensitive": true
238
+
},
239
+
"wordList": {
240
+
"values": ["4242"],
241
+
"isCaseSensitive": false
242
+
}
243
+
}
244
+
]
245
+
}
246
+
}
247
+
```
248
+
249
+
- exclusionType specifies either a REGEX or WORD_LIST
250
+
- regex field specifies a regex to trigger, if you choose to use REGEX type
251
+
- matchType could be either PARTIAL or FULL, To be a full match, the entire finding must match the regex pattern or word exactly, whereas findings containing more than just the regex pattern or word are considered partial matches. Example: suppose we have a finding of "4242-4242" with exclusion regex of 4242. If you use PARTIAL, this finding will be deactivated, while FULL not, since the regex only matches partial of the finding
102
252
103
253
## Additional Configuration
104
254
105
-
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.
255
+
You can add additional fields to your Nightfall config to ignore tokens and files from being flagged, as well as specify which files to exclusively scan.
Copy file name to clipboardExpand all lines: orb.yml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ jobs:
9
9
description: |
10
10
Scan Pull Requests and Commits for sensitive findings. You must set the NIGHTFALL_API_KEY as a CircleCI project environment variable to use this orb. View this orb's source and README for usage instructions.
Copy file name to clipboardExpand all lines: src/jobs/scan.yml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
description: |
2
2
Scan Pull Requests and Commits for sensitive findings. You must set the NIGHTFALL_API_KEY as a CircleCI project environment variable to use this orb. View this orb's source and README for usage instructions.
0 commit comments