palantir-security-basics

# Palantir Security Basics

## Overview
Security best practices for Foundry API tokens, OAuth2 credentials, scope management, and secret rotation. Covers both personal access tokens (dev) and service user credentials (production).

## Prerequisites
- Foundry Developer Console access
- Understanding of OAuth2 scopes

## Instructions

### Step 1: Secure Credential Storage
```bash
# .env — NEVER commit to git
FOUNDRY_HOSTNAME=mycompany.palantirfoundry.com
FOUNDRY_CLIENT_ID=your-client-id
FOUNDRY_CLIENT_SECRET=your-client-secret

# .gitignore — ensure .env files are excluded
echo '.env' >> .gitignore
echo '.env.local' >> .gitignore
echo '.env.*.local' >> .gitignore
```

For production, use a secrets manager:
```bash
# AWS Secrets Manager
aws secretsmanager create-secret --name foundry/prod \
  --secret-string '{"client_id":"xxx","client_secret":"yyy","hostname":"zzz"}'

# Google Cloud Secret Manager
echo -n "your-client-secret" | gcloud secrets create foundry-client-secret --data-file=-

# HashiCorp Vault
vault kv put secret/foundry client_id=xxx client_secret=yyy
```

### Step 2: Apply Least Privilege Scopes
| Environment | Recommended Scopes | Rationale |
|-------------|-------------------|-----------|
| Development | `api:read-data` | Read-only prevents accidental mutations |
| Staging | `api:read-data`, `api:write-data` | Test writes in safe environment |
| Production | Only scopes your app actually needs | Minimize blast radius |

```python
# Production app that only reads Ontology objects:
auth = foundry.ConfidentialClientAuth(
    client_id=os.environ["FOUNDRY_CLIENT_ID"],
    client_secret=os.environ["FOUNDRY_CLIENT_SECRET"],
    hostname=os.environ["FOUNDRY_HOSTNAME"],
    scopes=["api:ontology-read"],  # Minimum viable scope
)
```

### Step 3: Rotate Credentials
```bash
# 1. Generate new credentials in Developer Console
# 2. Deploy new credentials alongside old ones
# 3. Verify new credentials work
python -c "
import os, foundry
auth = foundry.ConfidentialClientAuth(
    client_id=os.environ['NEW_CLIENT_ID'],
    client_secret=os.environ['NEW_CLIENT_SECRET'],
    hostname=os.environ['FOUNDRY_HOSTNAME'],
    scopes=['api:read-data'],
)
auth.sign_in_as_service_user()
print('New credentials verified')
"
# 4. Remove old credentials from Developer Console
# 5. Update environment variables to use new credentials only
```

### Step 4: Validate Tokens Are Not Exposed
```bash
# Scan for leaked credentials in git history
git log --all -p | grep -i "foundry_token\|foundry_client_secret" | head -5
# If found: rotate immediately, then use git-filter-repo to remove

# Pre-commit hook to prevent committing secrets
# .pre-commit-config.yaml
# - repo: https://github.com/Yelp/detect-secrets
#   hooks:
#   - id: detect-secrets
```

### Step 5: Security Checklist
- [ ] Credentials in environment variables or secrets manager (never in code)
- [ ] `.env` files listed in `.gitignore`
- [ ] Separate credentials per environment (dev/staging/prod)
- [ ] Minimum scopes per application
- [ ] Personal access tokens used only for development
- [ ] OAuth2 client credentials for all production workloads
- [ ] Credential rotation schedule (every 90 days)
- [ ] Pre-commit hooks to detect leaked secrets

## Output
- Securely stored credentials using secrets manager
- Least-privilege scopes per environment
- Rotation procedure documented and tested
- Pre-commit hooks preventing secret commits

## Error Handling
| Security Issue | Detection | Mitigation |
|----------------|-----------|------------|
| Exposed token in git | `detect-secrets` scan | Rotate immediately, scrub history |
| Overly broad scopes | Audit app permissions | Reduce to minimum needed |
| Stale credentials | Age > 90 days | Rotate on schedule |
| Shared credentials | Multiple users same token | Create per-user service users |

## Resources
- [Foundry Authentication](https://www.palantir.com/docs/foundry/api/general/overview/authentication)
- [Developer Console](https://www.palantir.com/docs/foundry/ontology-sdk/create-a-new-osdk)
- [detect-secrets](https://github.com/Yelp/detect-secrets)

## Next Steps
For production deployment, see `palantir-prod-checklist`.