# 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)**

```bash
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)**

```bash
# 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
# .gitignore
settings
credentials
*_credentials.json
*.env
```

Verify:

```bash
git status --ignored
```

### Use Secret Management in CI/CD

**GitHub Actions:**

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

**Jenkins:**

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

**GitLab CI:**

```yaml
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 for all platforms. Each integration has its own `verify_ssl` setting:

```json
{
  "sealights":  { "verify_ssl": true },
  "jira":       { "verify_ssl": true },
  "ado":        { "verify_ssl": true },
  "scm":        { "verify_ssl": true },
  "confluence": { "verify_ssl": true }
}
```

All `verify_ssl` settings default to `true` and do not need to be listed explicitly unless you need to override them.

**Only disable SSL verification if:**

* The platform's certificate is not in your system's certificate keystore/trust store
* Your organization uses certificate interception (MITM proxy that replaces certificates)

Disable only for the affected platform rather than globally:

```json
{
  "jira": { "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:

```bash
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:**

```bash
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:

```bash
# 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:**

```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```

**Protect private keys:**

```bash
chmod 600 ~/.ssh/id_ed25519
```

**Use ssh-agent:**

```bash
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:**

```bash
# 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:**

```bash
# 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 for the affected platform only, e.g.: "confluence": { "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](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) - Set up secure configurations
* [Examples](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md) - Secure CI/CD examples
* [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) - Fix authentication issues


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/security-considerations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.