This guide covers the security architecture, best practices, compliance considerations, and incident response procedures for SciDK deployments.

⚠️ Status: implemented vs. recommended. This guide documents both controls that are implemented today and controls that are recommended / not yet implemented. Treat unmarked best-practice snippets (nginx, OS, compliance, monitoring) as deployment recommendations, not descriptions of current behavior. For the current security posture of the running app — including what is safe for single-user development vs. multi-user production — see SECURITY_HARDENING.md.

Implemented today: session-based login with bcrypt password hashing (scidk/core/auth.py), role-based access control with @require_role/@require_admin (scidk/web/decorators.py), per-user API tokens (Authorization: Bearer), the auth_users / auth_audit_log / auth_sessions tables, audit logging, manual session lock/unlock with auto-lock after inactivity, and Fernet-encrypted credentials in AlertManager/ConfigManager/API-endpoint registry and plugin settings (scidk/core/plugin_settings.py).

Recommended / not yet implemented:SESSION_COOKIE_SECURE / SESSION_COOKIE_HTTPONLY / SESSION_COOKIE_SAMESITE config, CSRF protection, password complexity enforcement, brute-force/lockout protection, and password reset or change (see inline notes below).

Only two roles exist: admin and user — auth_users enforces CHECK (role IN ('admin', 'user')) (scidk/core/auth.py:60), and require_role(*allowed_roles) is a flat membership test (scidk/web/decorators.py:94), not a hierarchy. "Any authenticated user" is @require_role('admin', 'user'); naming a role that does not exist locks out everyone including admins.

Verified against the code on 2026-08-04 (Cycle 5, Task C). The plugin_settings.py encryption is genuine cryptography.fernet.Fernet, not a placeholder — confirmed by the Cycle 2 audit and re-checked here; do not reintroduce a note claiming otherwise.

SciDK implements defense-in-depth security with multiple layers of protection:

1. Authentication & Authorization: Multi-user authentication with role-based access control (RBAC)
2. Data Encryption: Encryption at rest and in transit
3. Audit Logging: Comprehensive audit trails for all system activities
4. Session Management: Secure session handling with timeout controls
5. Input Validation: Protection against injection attacks
6. Secure Configuration: Encrypted credential storage

SciDK supports session-based authentication with the following features:

Password Security:

• Passwords hashed using bcrypt with salt
• Minimum password complexity requirements ⚠️recommended / not yet implemented — nothing in scidk/ enforces a length or complexity rule
• Protection against brute force attacks ⚠️recommended / not yet implemented — failed attempts are recorded in auth_audit_log but there is no rate limit and no account lockout
• Secure password reset mechanisms ⚠️recommended / not yet implemented — there is no password reset or change path; an admin recreates the user

Session Management:

• Session-based authentication, plus per-user API tokens via Authorization: Bearer
• Session validity is 24 hours (AuthManager.create_session(duration_hours=24)), not a short inactivity timeout. The 30-minute figure below is a recommendation, not current behavior
• Auto-lock after inactivity — implemented; a locked session answers 423 Locked until the password is re-entered (scidk/web/auth_middleware.py)
• Session invalidation on logout
• CSRF protection and secure-cookie flags (SESSION_COOKIE_SECURE/HTTPONLY/SAMESITE) ⚠️recommended / not yet implemented — no SESSION_COOKIE_* config or CSRF extension appears anywhere in scidk/

Example: Enabling Authentication⚠️illustrative only — the dict below is not a shape SciDK reads. Authentication is enabled through the Settings UI / auth_users table; session_timeout, password_min_length and require_complex_password are not consulted by any code path:

# ILLUSTRATIVE — not a supported config shape (see note above)auth_config= {
"enabled": True,
"session_timeout": 1800, # NOT read; sessions last duration_hours=24"password_min_length": 8, # NOT read; no length enforcement exists"require_complex_password": True# NOT read; no complexity enforcement exists
}

SciDK implements RBAC with the following roles:

Admin Role:

• Full system access
• User management capabilities
• Settings configuration
• Backup and restore operations
• Security configuration

User Role:

• Standard feature access
• File browsing and searching
• Graph visualization
• Chat interface
• Data exploration

Permissions Enforcement:

# Example permission check (internal)@require_role('admin')defdelete_user(user_id):
# Only admins can delete userspass

Best Practices:

1. Use strong, unique passwords (minimum 12 characters)
2. Enable multi-factor authentication (if available)
3. Limit admin accounts to necessary personnel
4. Regular password rotation (every 90 days)
5. Disable or remove unused accounts

Example: Creating Admin User:

# Via Python script
python3 -c "from scidk.core.auth import create_usercreate_user('admin', 'SecurePassword123!', role='admin')"

SQLite Database:

• File-level encryption using OS filesystem encryption
• Sensitive data (passwords, API keys) encrypted using Fernet (symmetric encryption)
• Encryption keys stored securely (not in version control)

Neo4j Database:

• Enterprise Edition supports transparent data encryption
• Community Edition: Use filesystem-level encryption

Example: Filesystem Encryption (Linux):

# LUKS encryption for data partition
sudo cryptsetup luksFormat /dev/sdb1
sudo cryptsetup luksOpen /dev/sdb1 encrypted_data
sudo mkfs.ext4 /dev/mapper/encrypted_data
sudo mount /dev/mapper/encrypted_data /var/lib/scidk

Backup Encryption:

# Encrypt backups with GPG
gpg --symmetric --cipher-algo AES256 backup.db

HTTPS/TLS: All production deployments should use HTTPS:

# nginx configurationserver{listen443ssl http2;ssl_certificate /etc/ssl/certs/scidk.crt;ssl_certificate_key /etc/ssl/private/scidk.key; # Strong SSL configurationssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';ssl_prefer_server_ciphers on; # HSTSadd_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;}

Neo4j TLS: Configure Neo4j to use encrypted Bolt connections:

# neo4j.conf
dbms.connector.bolt.tls_level=REQUIRED
dbms.ssl.policy.bolt.enabled=true
dbms.ssl.policy.bolt.base_directory=certificates/bolt

API Communication:

• All API endpoints should be accessed via HTTPS
• Credentials never transmitted in plain text
• Bearer tokens or session cookies for authentication

SciDK maintains comprehensive audit logs for:

1. User Authentication Events:

   • Login attempts (success/failure)
   • Logout events
   • Session expiration
   • Password changes

2. Data Access Events:

   • File access and downloads
   • Dataset queries
   • Graph queries
   • Export operations

3. Administrative Actions:

   • User creation/modification/deletion
   • Settings changes
   • Backup operations
   • System configuration changes

4. Security Events:

   • Failed authentication attempts
   • Permission denied errors
   • Suspicious activity patterns

{
"timestamp": "2024-01-15T10:30:00Z",
"event_type": "user.login",
"user": "admin",
"ip_address": "192.168.1.100",
"user_agent": "Mozilla/5.0...",
"status": "success",
"details": {
"session_id": "sess_abc123"
}
}

Via systemd journals:

sudo journalctl -u scidk | grep AUDIT

Via SQLite database — the table is auth_audit_log in scidk_settings.db, and timestamp is a REAL epoch-seconds value, not a SQLite datetime string:

SELECTtimestamp, username, action, details, ip_address
FROM auth_audit_log
WHEREtimestamp> strftime('%s', 'now', '-7 days')
ORDER BYtimestampDESC;

Recommended Retention Policies:

• Security events: 1 year minimum
• Authentication logs: 90 days minimum
• Administrative actions: 1 year minimum
• Data access: 30-90 days (or per compliance requirements)

Configure retention:

# systemd journal retention
sudo journalctl --vacuum-time=365d

1. Network Security:

• Deploy behind firewall
• Use private networks for database connections
• Limit exposed ports (only 443/80 for web, 7687 for internal Neo4j)
• Implement IP allowlisting for admin access

Example firewall rules (ufw):

# Allow HTTPS
sudo ufw allow 443/tcp
# Allow Neo4j only from app server
sudo ufw allow from 10.0.1.10 to any port 7687
# Deny all other incoming
sudo ufw default deny incoming
sudo ufw enable

2. Operating System Security:

• Keep OS and packages updated
• Use dedicated service account (non-root)
• Disable unnecessary services
• Configure SELinux/AppArmor policies

3. Database Security:

• Change default passwords immediately
• Use strong authentication credentials
• Regular security patches and updates
• Database access restricted to application only

4. Application Security:

• Run as non-privileged user
• Use virtual environment isolation
• Keep dependencies updated
• Regular security scanning

Best Practices:

1. Never commit credentials to version control
2. Use environment variables or secret management systems
3. Rotate credentials regularly (every 90 days)
4. Use different credentials for dev/test/prod
5. Encrypt credentials at rest

Example: Secret Management:

# Use environment variablesexport NEO4J_PASSWORD=$(vault read -field=password secret/neo4j)# Or use .env file (not in git)echo"NEO4J_AUTH=neo4j/$(openssl rand -base64 32)">> .env
chmod 600 .env

Credential Storage:

• SciDK stores encrypted credentials in SQLite. Fernet (symmetric) encryption is used for SMTP/alert credentials, config-manager secrets, API-endpoint auth tokens, and plugin settings (scidk/core/plugin_settings.py).
• Encryption key should be stored separately
• Consider using external secret managers (HashiCorp Vault, AWS Secrets Manager)

SciDK implements input validation to prevent:

SQL Injection:

• Parameterized queries for all database access
• ORM-based database interactions
• Input sanitization

Command Injection:

• No shell command construction from user input
• Subprocess calls use argument arrays (not shell=True)
• Path validation for filesystem operations

Cross-Site Scripting (XSS):

• HTML escaping in templates
• Content Security Policy headers
• Input sanitization

Path Traversal:

• Path normalization
• Validation against allowed directories
• No direct user input in file paths

Configuration⚠️Recommended / not yet implemented — the app does not currently set these cookie flags or enable CSRF protection; the snippet below is the recommended hardening to apply before multi-user production use:

# Flask session configuration (RECOMMENDED — not currently set in code)app.config.update(
SESSION_COOKIE_SECURE=True, # HTTPS onlySESSION_COOKIE_HTTPONLY=True, # No JavaScript accessSESSION_COOKIE_SAMESITE='Lax', # CSRF protectionPERMANENT_SESSION_LIFETIME=1800# 30 minutes
)

Session Management:

• Automatic session expiration
• Session invalidation on logout
• Session regeneration after privilege escalation
• Single sign-on support (if configured)

Recommended HTTP Security Headers:

# nginx configurationadd_header X-Frame-Options "SAMEORIGIN" always;add_header X-Content-Type-Options "nosniff" always;add_header X-XSS-Protection "1; mode=block" always;add_header Referrer-Policy "strict-origin-when-cross-origin" always;add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" always;add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

For healthcare data:

Required Controls:

1. Access Control: RBAC with unique user accounts
2. Audit Controls: Comprehensive audit logging
3. Integrity Controls: Data validation and checksums
4. Transmission Security: TLS/HTTPS for all communications
5. Authentication: Strong password policies
6. Encryption: Data encryption at rest and in transit

BAA Requirements:

• Ensure Business Associate Agreement with cloud providers
• Document security policies and procedures
• Regular security risk assessments
• Incident response procedures

PHI Handling:

• Minimize PHI exposure
• De-identify data when possible
• Secure disposal procedures
• Access logging for all PHI

For European data:

Right to Access:

• Provide user data export functionality
• API endpoints for data retrieval

Right to Erasure:

• User deletion removes all associated data
• Cascade delete for related records
• Audit log of deletions (without retaining PII)

Right to Portability:

• Export in machine-readable format (JSON, CSV)
• Configuration backup/export functionality

Data Protection:

• Encryption at rest and in transit
• Access controls and audit logs
• Privacy by design and default
• Data minimization

Breach Notification:

• 72-hour breach notification requirement
• Incident response procedures
• Contact data protection authorities

For service organizations:

Trust Services Criteria:

1. Security: Access controls, encryption, monitoring
2. Availability: Uptime, redundancy, disaster recovery
3. Processing Integrity: Data validation, error handling
4. Confidentiality: Encryption, access controls
5. Privacy: Data handling, consent management

Implementation:

• Document security policies
• Regular security assessments
• Vendor management
• Change management procedures
• Incident response plan

Update Process:

1. Monitor security advisories for dependencies
2. Test updates in staging environment
3. Schedule maintenance window
4. Apply updates and verify
5. Document changes

Automated Scanning:

# Scan Python dependencies
pip install safety
safety check
# Scan for vulnerabilities
npm audit # If using Node.js tools

Recommended Schedule:

• Annual penetration testing
• After major releases
• Before compliance audits

Testing Scope:

• Web application security
• API security
• Authentication mechanisms
• Database security
• Network security

Security Issue Reporting:

• Email: security@your-org.com
• PGP key available for encrypted reports
• Expected response time: 48 hours
• Coordinated disclosure policy

Phase 1: Detection

• Monitor audit logs for suspicious activity
• Alert system for security events
• User reports of suspicious behavior

Phase 2: Containment

• Isolate affected systems
• Disable compromised accounts
• Block malicious IP addresses
• Preserve evidence

Phase 3: Eradication

• Identify root cause
• Remove malicious code/access
• Patch vulnerabilities
• Reset compromised credentials

Phase 4: Recovery

• Restore from clean backups
• Verify system integrity
• Monitor for recurrence
• Gradual service restoration

Phase 5: Lessons Learned

• Document incident timeline
• Identify improvements
• Update procedures
• Train personnel

Security Breach Response:

# 1. Isolate the system
sudo systemctl stop scidk
sudo ufw deny from suspicious_ip
# 2. Preserve evidence
sudo journalctl -u scidk > incident_logs.txt
cp ~/.scidk/db/files.db incident_db_$(date +%Y%m%d).backup
# 3. Reset credentials
./scripts/reset_all_passwords.sh
# 4. Restore from known good backup
cp ~/.scidk/db/files.db.verified ~/.scidk/db/files.db
# 5. Restart with monitoring
sudo systemctl start scidk
tail -f /var/log/syslog | grep scidk

Data Breach Response:

1. Determine scope: What data was accessed?
2. Notify affected parties (per regulations)
3. Document the breach
4. Report to authorities (if required)
5. Implement additional controls

Internal Communication:

• Notify security team immediately
• Escalate to management within 1 hour
• Brief technical team on containment

External Communication:

• Notify affected users (if PII compromised)
• Regulatory notification (if required)
• Public disclosure (if significant breach)

Communication Template:

Subject: Security Incident Notification
We are writing to inform you of a security incident that occurred on [date].
Incident Type: [Unauthorized access / Data breach / etc.]
Data Affected: [Description]
Actions Taken: [Containment, investigation, etc.]
User Actions Required: [Password reset, etc.]
We take security seriously and have implemented additional measures...

Monitor for:

• Failed login attempts (>5 in 5 minutes)
• Unusual access patterns
• Large data exports
• Configuration changes
• Database connection errors

Alert Configuration:

# Example alert rulealert_rules= {
"failed_logins": {
"condition": "count > 5 in 5 minutes",
"action": "email_admin",
"severity": "high"
}
}

Track:

• Authentication success/failure rate
• Average session duration
• API error rates
• Disk space usage
• Database connection pool status

Regular Reviews:

• Daily: Security event review
• Weekly: Authentication pattern analysis
• Monthly: Comprehensive security audit
• Quarterly: Access control review

# Example log analysis# Failed logins
sudo journalctl -u scidk | grep "LOGIN_FAILED"| wc -l
# Unique IP addresses
sudo journalctl -u scidk | grep "LOGIN"| awk '{print $X}'| sort -u | wc -l

• Change all default passwords
• Enable HTTPS with valid certificates
• Configure firewall rules
• Enable authentication and RBAC
• Set strong session timeout
• Enable audit logging
• Encrypt sensitive data at rest
• Configure secure backup procedures
• Set up security monitoring and alerts
• Document incident response procedures
• Perform security assessment
• Train administrators on security procedures

• Review audit logs for anomalies
• Check for security updates
• Verify backup integrity
• Review user accounts and permissions
• Test disaster recovery procedures
• Review alert configurations
• Update documentation

• Deployment Guide: DEPLOYMENT.md
• Operations Manual: OPERATIONS.md
• Troubleshooting: TROUBLESHOOTING.md
• OWASP Top 10: https://owasp.org/www-project-top-ten/
• NIST Cybersecurity Framework: https://www.nist.gov/cyberframework
• CIS Controls: https://www.cisecurity.org/controls/