0
# Configuration
1

2
NSP supports multiple configuration methods including .nsprc files, environment variables, and command-line options for customizing vulnerability scanning behavior.
3

4
## Capabilities
5

6
### .nsprc Configuration Files
7

8
NSP uses the `rc` library to load configuration from .nsprc files in JSON format.
9

10
```javascript { .api }
11
/**
12
 * Configuration file format (.nsprc)
13
 * Supports JSON with comments via json-strip-comments
14
 */
15
interface NSPConfig {
16
  /** Array of advisory URLs to exclude from vulnerability reports */
17
  exceptions?: string[];
18
  /** Proxy server URL for API requests */
19
  proxy?: string; 
20
  /** Path to local advisories file for offline mode */
21
  advisoriesPath?: string;
22
}
23
```
24

25
**Configuration File Locations:**
26

27
NSP searches for .nsprc files in the following order:
28
1. Current project directory
29
2. User home directory
30
3. Command-line arguments override file settings
31

32
**Usage Examples:**
33

34
```javascript
35
// .nsprc in project root
36
{
37
  "exceptions": [
38
    "https://nodesecurity.io/advisories/123",
39
    "https://nodesecurity.io/advisories/456"
40
  ],
41
  "proxy": "http://proxy.company.com:8080",
42
  "advisoriesPath": "./local-advisories.json"
43
}
44

45
// .nsprc with comments (supported via json-strip-comments)
46
{
47
  // Exclude these advisories after security review
48
  "exceptions": [
49
    "https://nodesecurity.io/advisories/123" // Low impact for our use case
50
  ],
51
  
52
  // Corporate proxy configuration
53
  "proxy": "http://proxy.company.com:8080"
54
}
55
```
56

57
### Exception Handling
58

59
Configure exceptions to exclude specific advisories that have been reviewed and deemed acceptable.
60

61
```javascript { .api }
62
/**
63
 * Exception format - must be valid Node Security advisory URLs
64
 * Pattern: https://nodesecurity.io/advisories/[ADVISORY_ID]
65
 */
66
interface ExceptionConfig {
67
  exceptions: string[]; // Array of advisory URLs
68
}
69
```
70

71
**Exception URL Format:**
72

73
```javascript
74
// Valid exception URLs
75
const validExceptions = [
76
  "https://nodesecurity.io/advisories/123",
77
  "https://nodesecurity.io/advisories/456",
78
  "https://nodesecurity.io/advisories/789"
79
];
80

81
// Invalid formats (will be rejected)
82
const invalidExceptions = [
83
  "123", // Missing URL
84
  "https://example.com/123", // Wrong domain
85
  "https://nodesecurity.io/advisories/abc" // Non-numeric ID
86
];
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
// In .nsprc file
93
{
94
  "exceptions": [
95
    "https://nodesecurity.io/advisories/534" // Prototype pollution in lodash - reviewed and mitigated
96
  ]
97
}
98

99
// Via library API
100
nsp.check({
101
  package: './package.json',
102
  exceptions: ['https://nodesecurity.io/advisories/534']
103
}, callback);
104

105
// Via CLI
106
nsp check # Uses exceptions from .nsprc file
107
```
108

109
### Proxy Configuration
110

111
Configure proxy servers for environments that require HTTP proxies for external API access.
112

113
```javascript { .api }
114
/**
115
 * Proxy configuration supports multiple methods
116
 */
117
interface ProxyConfig {
118
  // .nsprc file setting
119
  proxy?: string;
120
  
121
  // Environment variables (checked in order)
122
  // process.env.https_proxy
123
  // process.env.HTTPS_PROXY
124
  
125
  // Library API option
126
  // options.proxy
127
}
128
```
129

130
**Supported Proxy Protocols:**
131

132
- `http://` - HTTP proxy
133
- `https://` - HTTPS proxy  
134
- `socks://` - SOCKS v5 proxy with optional authentication
135
- `socks5://` - SOCKS v5 proxy with optional authentication
136
- `socks4://` - SOCKS v4 proxy
137
- `pac+http://` - PAC (Proxy Auto-Configuration) file
138

139
**Usage Examples:**
140

141
```javascript
142
// .nsprc configuration
143
{
144
  "proxy": "http://proxy.company.com:8080"
145
}
146

147
// Environment variable
148
export HTTPS_PROXY=http://proxy.company.com:8080
149
nsp check
150

151
// With authentication
152
{
153
  "proxy": "http://username:password@proxy.company.com:8080"
154
}
155

156
// SOCKS proxy
157
{
158
  "proxy": "socks5://proxy.company.com:1080"
159
}
160

161
// Library API
162
nsp.check({
163
  package: './package.json',
164
  proxy: 'http://proxy.company.com:8080'
165
}, callback);
166
```
167

168
### Advisories Path Configuration
169

170
Configure the path to local advisories file for offline mode operation.
171

172
```javascript { .api }
173
/**
174
 * Advisories path configuration for offline mode
175
 */
176
interface AdvisoriesPathConfig {
177
  advisoriesPath?: string; // Path to local advisories.json file
178
}
179
```
180

181
**Setup Process:**
182

183
```bash
184
# 1. Download advisory database
185
npm run setup-offline
186

187
# 2. Configure path in .nsprc
188
{
189
  "advisoriesPath": "./advisories.json"
190
}
191

192
# 3. Use offline mode
193
nsp check --offline
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
// .nsprc configuration
200
{
201
  "advisoriesPath": "/path/to/advisories.json"
202
}
203

204
// Relative path (resolved from current working directory)
205
{
206
  "advisoriesPath": "./security/advisories.json" 
207
}
208

209
// Library API
210
nsp.check({
211
  package: './package.json',
212
  shrinkwrap: './npm-shrinkwrap.json',
213
  offline: true,
214
  advisoriesPath: './advisories.json'
215
}, callback);
216

217
// CLI usage
218
nsp check --offline --advisoriesPath ./advisories.json
219
```
220

221
### Environment Variables
222

223
Environment variables that affect NSP behavior.
224

225
```javascript { .api }
226
/**
227
 * Environment variables recognized by NSP
228
 */
229
interface EnvironmentConfig {
230
  /** HTTPS proxy URL (lowercase) */
231
  https_proxy?: string;
232
  /** HTTPS proxy URL (uppercase) */
233
  HTTPS_PROXY?: string;
234
}
235
```
236

237
**Priority Order:**
238
1. Command-line options (highest priority)
239
2. .nsprc file settings
240
3. Environment variables (lowest priority)
241

242
**Usage Examples:**
243

244
```bash
245
# Set proxy via environment
246
export HTTPS_PROXY=http://proxy.company.com:8080
247
nsp check
248

249
# Temporary proxy for single command
250
HTTPS_PROXY=http://proxy.company.com:8080 nsp check
251

252
# Mixed configuration (proxy from env, exceptions from .nsprc)
253
export HTTPS_PROXY=http://proxy.company.com:8080
254
echo '{"exceptions": ["https://nodesecurity.io/advisories/123"]}' > .nsprc
255
nsp check
256
```
257

258

259
### Configuration Validation
260

261
NSP validates configuration options using Joi schema validation.
262

263
```javascript { .api }
264
/**
265
 * Configuration validation rules
266
 */
267
interface ConfigValidation {
268
  exceptions: string[]; // Must be valid advisory URLs matching regex pattern
269
  proxy: string; // Must be valid URL format
270
  advisoriesPath: string; // Must be valid file path
271
}
272

273
// Exception URL validation regex: /^https\:\/\/nodesecurity\.io\/advisories\/([0-9]+)$/
274
```
275

276
**Validation Examples:**
277

278
```javascript
279
// Valid configuration
280
{
281
  "exceptions": ["https://nodesecurity.io/advisories/123"],
282
  "proxy": "http://proxy.example.com:8080",
283
  "advisoriesPath": "./advisories.json"
284
}
285

286
// Invalid configuration (will cause errors)
287
{
288
  "exceptions": ["invalid-url"], // Invalid URL format 
289
  "proxy": "not-a-url", // Invalid proxy URL
290
  "advisoriesPath": 123 // Should be string
291
}
292
```
293

294
### Configuration Debugging
295

296
Debug configuration loading and resolution:
297

298
```javascript
299
// Check effective configuration
300
const Conf = require('rc')('nsp', {
301
  api: {
302
    baseUrl: 'https://api.nodesecurity.io'
303
  }
304
});
305

306
console.log('Loaded configuration:', Conf);
307
console.log('Exceptions:', Conf.exceptions);
308
console.log('Proxy:', Conf.proxy);
309
console.log('Advisories path:', Conf.advisoriesPath);
310
```