Security Considerations

Best practices for securing the User Story Coverage Tagging tool and protecting credentials.

Overview

This tool runs locally in your environment and generates reports on your systems. The security profile is relatively low-risk:

What stays in your environment:

• All generated reports (HTML, JSON, Confluence pages, Jira/ADO updates)

• Source code and repository access

• Report data and coverage metrics

What is sent to SeaLights:

• Tagging data: ticket IDs + file paths (during tagging phase)

• API requests to read coverage data (during report phase)

What is sent to other systems:

• Jira/ADO: Coverage percentages and summaries (if using US4 scripts)

• Confluence: Coverage report pages (if using US3 script)

• GitHub/GitLab/Bitbucket: Read-only access to PRs and commits

Primary security concerns:

1. Protecting API tokens from unauthorized access

2. Standard file system security for generated reports

3. Network security for API communications

---

Credential Management

Store Credentials Securely

Recommended approaches:

Option 1: Environment Variables (for CI/CD)

export SEALIGHTS_API_TOKEN="your-token"
export JIRA_AUTHORIZATION="Basic encoded-credentials"
python3 US1_RPT_create_report_info_files.py --settings settings

Option 2: Separate Credentials File (for local use)

# base_settings - committed to git
{
  "output_folder": "./reports",
  "test_stages": [...]
}

# credentials - NOT committed (in .gitignore)
{
  "sealights": {"api_token": "your-token"},
  "jira": {"authorization": "Basic ..."}
}

# Usage
python3 script.py --settings base_settings --settings credentials

Protect Settings Files

Add credentials files to .gitignore:

# .gitignore
settings
credentials
*_credentials.json
*.env

Verify:

git status --ignored

Use Secret Management in CI/CD

GitHub Actions:

env:
  SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
  JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}

Jenkins:

environment {
    SEALIGHTS_TOKEN = credentials('sealights-token')
}

GitLab CI:

variables:
  SEALIGHTS_API_TOKEN:
    masked: true
    protected: true

---

API Token Security

Token Permissions (Least Privilege)

SeaLights API Token:

• Read: apps, branches, builds, coverage reports

• Write: tag methods with ticket IDs

GitHub/GitLab/Bitbucket Token:

• Read: repositories, pull requests, commits

• No write permissions needed

Jira API Token:

• Read: projects matching your JQL query

• Write: Only if using US4_RPT_update_jira.py to update custom fields

Azure DevOps PAT:

• Work Items: Read

• Extension Data: Read & Write (only if using US4_RPT_update_ado_plugin.py)

Token Rotation

Recommended schedule:

• Production/CI: Every 90 days

• Development: Every 6-12 months

Steps:

1. Generate new token in web UI

2. Update environment variables or secret manager

3. Test with new token

4. Revoke old token

If a Token is Compromised

1. Revoke immediately in the web UI

2. Generate new token

3. Update all systems using it

4. Review audit logs for unauthorized usage

---

Network Security

SSL/TLS Verification

Always enable SSL verification:

{
  "sealights": {
    "verify_ssl": true
  }
}

Only disable SSL verification if:

• SeaLights certificate is not in your system's certificate keystore/trust store

• Your organization uses certificate interception (MITM proxy that replaces certificates)

{
  "sealights": {
    "verify_ssl": false
  }
}

Preferred solution for certificate issues: Install the missing certificate in your system's trust store rather than disabling verification.

Corporate Proxies

If behind a corporate proxy:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
python3 script.py --settings settings

Required Outbound Access

The tool needs HTTPS (port 443) access to:

• SeaLights: https://*.sealights.co

• Jira: Your Jira instance URL

• Azure DevOps: https://dev.azure.com

• GitHub/GitLab/Bitbucket: Your SCM platform

• Git repositories: Port 22 (SSH) or 443 (HTTPS)

---

Local Data Security

Report File Permissions

Generated reports contain coverage data and may include:

• File paths and method signatures

• Ticket titles and descriptions

• Developer names (from issue trackers)

Set appropriate permissions:

chmod 700 reports/              # Only owner can access
chmod 600 reports/*.html        # Read/write for owner only

Data Retention

Clean up old reports based on your needs:

# Delete reports older than 90 days
find reports/ -name "*.html" -mtime +90 -delete
find reports/ -name "ReportInfo_*.json" -mtime +90 -delete

Logs and Debug Output

The tool automatically masks sensitive data in logs:

"api_token": "abc1...xyz9"  # Only first/last 4 chars shown

When troubleshooting with --log-level DEBUG, logs may contain API responses. Don't share debug logs publicly without reviewing them first.

---

Git Repository Access

Skip this section if:

• Using SeaLights auto-tagging

• Only generating reports (US_RPT_* scripts)

• Using GitHub PR-based tagging (doesn't clone repos)

Only relevant if using US_SRC_tag_repos_by_history.py which clones/pulls repositories.

SSH Key Security

For scripts that clone repositories:

Generate secure keys:

ssh-keygen -t ed25519 -C "[email protected]"

Protect private keys:

chmod 600 ~/.ssh/id_ed25519

Use ssh-agent:

eval $(ssh-agent -s)
ssh-add ~/.ssh/id_ed25519

Deploy Keys vs Personal Keys

• CI/CD: Use deploy keys (read-only, repository-specific)

• Development: Personal SSH keys are fine

• Never: Share or commit private keys

---

CI/CD Pipeline Security

Store Secrets Properly

Do:

• Use built-in secret managers (GitHub Secrets, Jenkins Credentials, etc.)

• Mark secrets as masked/protected

• Use separate service accounts for automation

Don't:

• Echo secrets in logs

• Commit secrets to repositories

• Share secrets between projects unnecessarily

Isolate Builds

Use ephemeral build environments when possible:

• Credentials don't persist after build

• Fresh environment each run

• No cross-contamination between builds

---

Access Control

Principle of Least Privilege

For CI/CD:

• Create dedicated service account in Jira/ADO

• Grant minimum required permissions

• Monitor usage in audit logs

For Developers:

• Use personal tokens with appropriate scope

• Revoke tokens when leaving team/project

---

Confluence and Issue Tracker Updates

When publishing reports to Confluence or updating Jira/ADO:

Confluence Pages

• Coverage pages inherit space permissions

• Use appropriate space access controls

• Consider using private spaces for sensitive projects

Jira/ADO Custom Fields

• Coverage data inherits ticket permissions

• Users see coverage only for tickets they can access

• No additional security configuration needed

---

What You Don't Need to Worry About

Since reports stay in your environment:

• Report data encryption - Standard file system security is sufficient

• Report transmission security - Reports aren't transmitted anywhere

• Complex data classification - Coverage metrics are typically internal-use data

• Extensive audit logging - Standard system logs are usually adequate

Focus your security efforts on protecting API tokens and following standard file security practices.

---

Troubleshooting Security Issues

SSL Certificate Errors

If you encounter SSL verification errors:

Certificate not in trust store:

# Install the missing certificate
sudo cp missing-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Or set environment variable to custom CA bundle
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt

Certificate interception by corporate proxy:

# Option 1: Install proxy's CA certificate (preferred)
sudo cp proxy-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Option 2: Disable verification (not recommended)
# Set in settings: "verify_ssl": false

Authentication Failures

SeaLights 401 Unauthorized:

• Token may be expired or invalid

• Generate new token in SeaLights web UI

Jira/ADO 401/403:

• Verify credentials encoding: echo -n "user:token" | base64

• Check user has read access to projects in JQL/WIQL

GitHub/GitLab 401:

• Token may be expired

• Verify token has repo or public_repo scope

Git Authentication

Permission denied (publickey):

• SSH key not added: ssh-add ~/.ssh/id_ed25519

• Public key not added to GitHub/GitLab/Bitbucket

Could not read Username:

• Use SSH URLs instead of HTTPS

• Or configure git credential helper

---

If Credentials Are Compromised

1. Revoke token immediately in web UI

2. Generate new token

3. Update environment variables/secret manager

4. Review audit logs for unauthorized access

5. Update security procedures to prevent recurrence

---

Summary

Key Security Points:

• Reports stay in your environment (low risk)

• Protect API tokens like passwords

• Use environment variables or secret managers for credentials

• Enable SSL verification unless certificate issues prevent it

• Follow standard file system security practices

• Rotate tokens regularly (every 90 days for production)

The security model is straightforward: Protect your API tokens, and you protect your systems.

---

Next Steps

• Configuration Guide - Set up secure configurations

• Examples - Secure CI/CD examples

• Troubleshooting - Fix authentication issues