@genobank/biofs 1.6.0 → 1.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/settings.local.json +33 -0
- package/BUBBLEWRAP_INTEGRATION.md +486 -0
- package/BUBBLEWRAP_QUICKSTART.md +356 -0
- package/BUBBLEWRAP_README.md +466 -0
- package/BUBBLEWRAP_STRATEGIC_ANALYSIS.md +625 -0
- package/CHANGELOG.md +73 -0
- package/ENHANCEMENT_DOCUMENTATION.md +218 -0
- package/GEMINI_REMOVAL_COMPLETE.md +311 -0
- package/dist/commands/login.d.ts +2 -0
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +30 -5
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/sandbox.d.ts +10 -0
- package/dist/commands/sandbox.d.ts.map +1 -0
- package/dist/commands/sandbox.js +418 -0
- package/dist/commands/sandbox.js.map +1 -0
- package/dist/commands/tokenize.js +37 -462
- package/dist/index.js +6 -33
- package/dist/index.js.map +1 -1
- package/dist/lib/ai/classifier.d.ts +12 -0
- package/dist/lib/ai/classifier.d.ts.map +1 -1
- package/dist/lib/ai/classifier.js +178 -0
- package/dist/lib/ai/classifier.js.map +1 -0
- package/dist/lib/bioip/collections.js +1 -3
- package/dist/lib/config/constants.d.ts.map +1 -1
- package/dist/lib/config/constants.js +2 -0
- package/dist/lib/config/constants.js.map +1 -1
- package/dist/lib/sandbox/bubblewrap.d.ts +125 -0
- package/dist/lib/sandbox/bubblewrap.d.ts.map +1 -0
- package/dist/lib/sandbox/bubblewrap.js +343 -0
- package/dist/lib/sandbox/bubblewrap.js.map +1 -0
- package/dist/lib/utils/logger.d.ts +6 -5
- package/dist/lib/utils/logger.d.ts.map +1 -1
- package/dist/lib/utils/logger.js +23 -5
- package/dist/lib/utils/logger.js.map +1 -1
- package/examples/sandbox-usage.ts +361 -0
- package/package.json +3 -2
- package/SECURITY_AUDIT_20251010.md +0 -159
- package/dist/commands/tokenize.js.bkp.20251010_022629 +0 -906
- package/dist/index.js.bkp.20251010_045250 +0 -417
|
@@ -0,0 +1,356 @@
|
|
|
1
|
+
# Bubblewrap Integration - Quick Start Guide
|
|
2
|
+
|
|
3
|
+
## 5-Minute Setup
|
|
4
|
+
|
|
5
|
+
### Step 1: Install Bubblewrap
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Ubuntu/Debian
|
|
9
|
+
sudo apt-get update && sudo apt-get install -y bubblewrap
|
|
10
|
+
|
|
11
|
+
# Verify installation
|
|
12
|
+
bwrap --version
|
|
13
|
+
# Output: bubblewrap 0.8.0
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
### Step 2: Enable Sandboxing in BioFS
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# Check current status
|
|
20
|
+
biofs sandbox status
|
|
21
|
+
|
|
22
|
+
# Enable for all operations
|
|
23
|
+
biofs sandbox enable --all
|
|
24
|
+
|
|
25
|
+
# Or enable selectively
|
|
26
|
+
biofs sandbox enable --downloads --processing
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Step 3: Verify Configuration
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Run sandbox tests
|
|
33
|
+
biofs sandbox test
|
|
34
|
+
|
|
35
|
+
# Expected output:
|
|
36
|
+
# ✓ Bubblewrap is available
|
|
37
|
+
# ✓ Basic execution works
|
|
38
|
+
# ✓ Network isolation works
|
|
39
|
+
# ✓ Filesystem isolation works
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Step 4: Use Sandboxed Operations
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
# Downloads now run in sandbox (if enabled)
|
|
46
|
+
biofs download biocid://0x.../vcf/genome.vcf --sandboxed
|
|
47
|
+
|
|
48
|
+
# Jobs run in isolated environment
|
|
49
|
+
biofs job create "Find cancer variants" genome.vcf --sandboxed
|
|
50
|
+
|
|
51
|
+
# Processing with network isolation
|
|
52
|
+
biofs process genome.vcf --sandboxed --no-network
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## What Does Sandboxing Do?
|
|
58
|
+
|
|
59
|
+
### Without Sandboxing
|
|
60
|
+
```
|
|
61
|
+
┌─────────────────────────────────────┐
|
|
62
|
+
│ biofs download genome.vcf │
|
|
63
|
+
│ │
|
|
64
|
+
│ • Full network access │
|
|
65
|
+
│ • Can read all user files │
|
|
66
|
+
│ • Can modify system │
|
|
67
|
+
│ • Credentials exposed │
|
|
68
|
+
│ • No process isolation │
|
|
69
|
+
└─────────────────────────────────────┘
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### With Sandboxing
|
|
73
|
+
```
|
|
74
|
+
┌─────────────────────────────────────┐
|
|
75
|
+
│ biofs download genome.vcf │
|
|
76
|
+
│ ↓ │
|
|
77
|
+
│ ┌───────────────────────────┐ │
|
|
78
|
+
│ │ Bubblewrap Sandbox │ │
|
|
79
|
+
│ │ │ │
|
|
80
|
+
│ │ ✓ Network controlled │ │
|
|
81
|
+
│ │ ✓ Only sees genome.vcf │ │
|
|
82
|
+
│ │ ✓ Cannot modify system │ │
|
|
83
|
+
│ │ ✓ Credentials read-only │ │
|
|
84
|
+
│ │ ✓ Process isolated │ │
|
|
85
|
+
│ └───────────────────────────┘ │
|
|
86
|
+
└─────────────────────────────────────┘
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Security Comparison
|
|
92
|
+
|
|
93
|
+
| Threat | Risk Without Sandbox | Risk With Sandbox |
|
|
94
|
+
|--------|---------------------|-------------------|
|
|
95
|
+
| **Malicious VCF file exploits parser** | ✗ Full system compromise | ✓ Isolated - no system access |
|
|
96
|
+
| **Researcher accidentally uploads genomic data** | ✗ Data exfiltrated | ✓ Network blocked |
|
|
97
|
+
| **Credential theft** | ✗ Full credential access | ✓ Read-only, isolated |
|
|
98
|
+
| **Ransomware in analysis tool** | ✗ Encrypts all files | ✓ Cannot access user files |
|
|
99
|
+
| **Supply chain attack in dependency** | ✗ Backdoor installed | ✓ Cannot persist on system |
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Real-World Examples
|
|
104
|
+
|
|
105
|
+
### Example 1: Secure Download of Genomic Data
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# User requests genomic data
|
|
109
|
+
biofs download biocid://0x5f5a.../vcf/patient_genome.vcf
|
|
110
|
+
|
|
111
|
+
# What happens with sandboxing:
|
|
112
|
+
# 1. Check GDPR consent ✓
|
|
113
|
+
# 2. Create isolated environment
|
|
114
|
+
# 3. Mount only output directory
|
|
115
|
+
# 4. Download file (network allowed, read-only credentials)
|
|
116
|
+
# 5. Verify integrity
|
|
117
|
+
# 6. Move to final location
|
|
118
|
+
# 7. Destroy sandbox
|
|
119
|
+
|
|
120
|
+
# Security guarantees:
|
|
121
|
+
# • Credentials never in main process
|
|
122
|
+
# • Downloaded file cannot modify system
|
|
123
|
+
# • Consent verified before access
|
|
124
|
+
# • Audit trail recorded
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Example 2: Network-Isolated Processing
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
# Process VCF file locally (no cloud)
|
|
131
|
+
biofs process genome.vcf --analysis cancer-variants --sandboxed
|
|
132
|
+
|
|
133
|
+
# What happens:
|
|
134
|
+
# 1. Create sandbox with NO network access
|
|
135
|
+
# 2. Mount genome.vcf as read-only
|
|
136
|
+
# 3. Mount output directory as read-write
|
|
137
|
+
# 4. Run analysis tool
|
|
138
|
+
# 5. Tool CANNOT upload data anywhere (no network!)
|
|
139
|
+
# 6. Results written to output directory
|
|
140
|
+
# 7. Destroy sandbox
|
|
141
|
+
|
|
142
|
+
# Security guarantees:
|
|
143
|
+
# • Data exfiltration IMPOSSIBLE
|
|
144
|
+
# • Even if tool is malicious, data stays local
|
|
145
|
+
# • GDPR Article 32 compliance
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Example 3: Research Job Execution
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
# Run bioinformatics pipeline
|
|
152
|
+
biofs job create "Compare trio variants" \
|
|
153
|
+
--input father.vcf \
|
|
154
|
+
--input mother.vcf \
|
|
155
|
+
--input child.vcf \
|
|
156
|
+
--sandboxed
|
|
157
|
+
|
|
158
|
+
# What happens:
|
|
159
|
+
# 1. Job runs in isolated container
|
|
160
|
+
# 2. Only sees the 3 VCF files
|
|
161
|
+
# 3. Cannot access internet (unless explicitly allowed)
|
|
162
|
+
# 4. Cannot see other researchers' data
|
|
163
|
+
# 5. Results written to isolated output directory
|
|
164
|
+
# 6. Sandbox destroyed after completion
|
|
165
|
+
|
|
166
|
+
# Security guarantees:
|
|
167
|
+
# • Multi-tenant isolation
|
|
168
|
+
# • No data cross-contamination
|
|
169
|
+
# • Resource limits enforced
|
|
170
|
+
# • Audit trail for compliance
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Configuration Examples
|
|
176
|
+
|
|
177
|
+
### Minimal Security (Development)
|
|
178
|
+
```json
|
|
179
|
+
{
|
|
180
|
+
"security": {
|
|
181
|
+
"sandbox": {
|
|
182
|
+
"enabled": true,
|
|
183
|
+
"enforceForSensitiveData": false,
|
|
184
|
+
"operations": {
|
|
185
|
+
"download": { "enabled": false },
|
|
186
|
+
"upload": { "enabled": false },
|
|
187
|
+
"processing": { "enabled": true, "isolateNetwork": false },
|
|
188
|
+
"jobs": { "enabled": false }
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Balanced Security (Production)
|
|
196
|
+
```json
|
|
197
|
+
{
|
|
198
|
+
"security": {
|
|
199
|
+
"sandbox": {
|
|
200
|
+
"enabled": true,
|
|
201
|
+
"enforceForSensitiveData": true,
|
|
202
|
+
"operations": {
|
|
203
|
+
"download": { "enabled": true, "isolateNetwork": false },
|
|
204
|
+
"upload": { "enabled": true, "isolateNetwork": false },
|
|
205
|
+
"processing": { "enabled": true, "isolateNetwork": true },
|
|
206
|
+
"jobs": { "enabled": true, "isolateNetwork": false }
|
|
207
|
+
},
|
|
208
|
+
"security": {
|
|
209
|
+
"isolateNetwork": true,
|
|
210
|
+
"isolatePID": true,
|
|
211
|
+
"isolateIPC": true,
|
|
212
|
+
"enableSeccomp": true,
|
|
213
|
+
"dropCapabilities": true
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### Maximum Security (High-Risk Data)
|
|
221
|
+
```json
|
|
222
|
+
{
|
|
223
|
+
"security": {
|
|
224
|
+
"sandbox": {
|
|
225
|
+
"enabled": true,
|
|
226
|
+
"enforceForSensitiveData": true,
|
|
227
|
+
"operations": {
|
|
228
|
+
"download": {
|
|
229
|
+
"enabled": true,
|
|
230
|
+
"isolateNetwork": false,
|
|
231
|
+
"timeout": 3600
|
|
232
|
+
},
|
|
233
|
+
"upload": {
|
|
234
|
+
"enabled": true,
|
|
235
|
+
"isolateNetwork": false,
|
|
236
|
+
"timeout": 7200
|
|
237
|
+
},
|
|
238
|
+
"processing": {
|
|
239
|
+
"enabled": true,
|
|
240
|
+
"isolateNetwork": true,
|
|
241
|
+
"timeout": 1800
|
|
242
|
+
},
|
|
243
|
+
"jobs": {
|
|
244
|
+
"enabled": true,
|
|
245
|
+
"isolateNetwork": true,
|
|
246
|
+
"timeout": 86400
|
|
247
|
+
}
|
|
248
|
+
},
|
|
249
|
+
"security": {
|
|
250
|
+
"isolateNetwork": true,
|
|
251
|
+
"isolatePID": true,
|
|
252
|
+
"isolateIPC": true,
|
|
253
|
+
"enableSeccomp": true,
|
|
254
|
+
"dropCapabilities": true
|
|
255
|
+
},
|
|
256
|
+
"gdprEnforcement": {
|
|
257
|
+
"requireConsentBeforeMount": true,
|
|
258
|
+
"auditAllAccess": true,
|
|
259
|
+
"preventExfiltration": true
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Performance FAQ
|
|
269
|
+
|
|
270
|
+
**Q: Will sandboxing slow down my downloads?**
|
|
271
|
+
A: No. Overhead is <1%. A 10GB file downloads at native speed.
|
|
272
|
+
|
|
273
|
+
**Q: What about VCF annotation jobs?**
|
|
274
|
+
A: Sandbox startup is ~15ms. For jobs running hours, this is negligible.
|
|
275
|
+
|
|
276
|
+
**Q: Does it use more memory?**
|
|
277
|
+
A: No. Namespaces share memory. Only isolated metadata is duplicated.
|
|
278
|
+
|
|
279
|
+
**Q: Can I disable it for specific operations?**
|
|
280
|
+
A: Yes. Use `biofs download genome.vcf --no-sandbox` to bypass.
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## Troubleshooting
|
|
285
|
+
|
|
286
|
+
### "bwrap: command not found"
|
|
287
|
+
```bash
|
|
288
|
+
sudo apt-get install bubblewrap
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
### "Operation not permitted" on namespace creation
|
|
292
|
+
```bash
|
|
293
|
+
# Enable user namespaces
|
|
294
|
+
sudo sysctl kernel.unprivileged_userns_clone=1
|
|
295
|
+
|
|
296
|
+
# Make permanent
|
|
297
|
+
echo 'kernel.unprivileged_userns_clone=1' | sudo tee -a /etc/sysctl.conf
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
### "Mount source does not exist"
|
|
301
|
+
```bash
|
|
302
|
+
# Check allowed mounts in config
|
|
303
|
+
biofs sandbox config
|
|
304
|
+
|
|
305
|
+
# Add missing directory
|
|
306
|
+
mkdir -p ~/Downloads/genobank
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Performance issues
|
|
310
|
+
```bash
|
|
311
|
+
# Check if seccomp is causing problems
|
|
312
|
+
biofs sandbox status
|
|
313
|
+
|
|
314
|
+
# Temporarily disable seccomp
|
|
315
|
+
# Edit ~/.genobank/config.json:
|
|
316
|
+
# "enableSeccomp": false
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## GDPR Compliance Checklist
|
|
322
|
+
|
|
323
|
+
Use sandboxing to satisfy GDPR requirements:
|
|
324
|
+
|
|
325
|
+
- ✅ **Article 25 (Privacy by Design)**: Sandboxing enforces minimal data access
|
|
326
|
+
- ✅ **Article 32 (Security)**: Technical measures against unauthorized access
|
|
327
|
+
- ✅ **Article 9 (Special Categories)**: Protected processing of genetic data
|
|
328
|
+
- ✅ **Article 5(1)(f) (Integrity)**: Prevents unauthorized modification
|
|
329
|
+
- ✅ **Article 15 (Right of Access)**: Audit logs prove controlled access
|
|
330
|
+
- ✅ **Article 17 (Right to Erasure)**: Sandboxes are ephemeral, no persistence
|
|
331
|
+
|
|
332
|
+
**Document this in your DPA (Data Processing Agreement):**
|
|
333
|
+
|
|
334
|
+
> "Genomic data processing utilizes Linux namespace isolation (bubblewrap)
|
|
335
|
+
> to ensure network isolation, process isolation, and filesystem isolation,
|
|
336
|
+
> implementing appropriate technical measures as required by GDPR Article 32."
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Next Steps
|
|
341
|
+
|
|
342
|
+
1. **Enable sandboxing**: `biofs sandbox enable --all`
|
|
343
|
+
2. **Run tests**: `biofs sandbox test`
|
|
344
|
+
3. **Try examples**: `ts-node examples/sandbox-usage.ts`
|
|
345
|
+
4. **Read full docs**: See `BUBBLEWRAP_INTEGRATION.md`
|
|
346
|
+
5. **Configure for your needs**: `biofs sandbox config --edit`
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## Support
|
|
351
|
+
|
|
352
|
+
- **Issues**: https://github.com/Genobank/biofs-cli/issues
|
|
353
|
+
- **Email**: support@genobank.io
|
|
354
|
+
- **Docs**: https://docs.genobank.io
|
|
355
|
+
|
|
356
|
+
**Security concerns?** Email: security@genobank.io
|