SecureDX

 ____                           ____  __  __
/ ___|  ___  ___ _   _ _ __ ___|  _ \ \ \/ /
\___ \ / _ \/ __| | | | '__/ _ \ | | | \  / 
 ___) |  __/ (__| |_| | | |  __/ |_| | /  \ 
|____/ \___|\___|\__,_|_|  \___|____/ /_/\_\

Graduated Security Gates for DevSecOps Pipelines

SecureDX is an enterprise-grade DevSecOps tool that integrates graduated security gates directly into developer workflows. It provides static application security testing (SAST), secrets detection, Infrastructure as Code (IaC) scanning, and data residency analysis with configurable severity thresholds based on CVSS scoring.

Developed by HERO CONTROL SYSTEMS LTD, Lusaka, Zambia.

Table of Contents

1. Overview
2. Compliance Frameworks
3. System Requirements
4. Installation
5. Quick Start
6. Command Reference
7. Configuration
8. Scanner Modules
9. Language Support
10. CI/CD Integration
11. Programmatic API
12. Security Model
13. License
14. Support

Overview

SecureDX implements a graduated security gate architecture that categorises findings into three decision outcomes: BLOCK, WARN, and PASS. This approach balances security enforcement with developer productivity by allowing teams to configure thresholds appropriate to their risk tolerance.

Core Capabilities

Architecture

SecureDX operates entirely locally with no external telemetry by default. All scan results, analytics, and configuration are stored within the project directory under .securedx/. The tool is designed to function in air-gapped environments and does not require network connectivity for core scanning operations.

Compliance Frameworks

SecureDX maps security findings to industry-standard compliance frameworks, enabling organisations to generate audit-ready evidence.

The Data Residency scanner specifically addresses Zambia Data Protection Act compliance by identifying personal data storage locations, flagging cross-border transfers, and detecting endpoints in jurisdictions without adequate data protection agreements with Zambia.

System Requirements

Installation

Global Installation (Recommended)

npm install -g securedx

Project-Level Installation

npm install --save-dev securedx

Verification

securedx --version

Quick Start

1. Initialise Project

securedx init

This creates a securedx.config.json configuration file and optionally installs Git hooks.

2. Run Security Scan

securedx scan

3. View Report

securedx report

Command Reference

securedx init

Initialise SecureDX in the current project directory.

securedx init              # Interactive configuration
securedx init -y           # Accept default configuration
securedx init --ci         # Configure for CI/CD environment
securedx init --no-hooks   # Skip Git hook installation

securedx scan

Execute security scans on the codebase.

securedx scan              # Full scan (all scanners)
securedx scan --staged     # Scan staged files only
securedx scan --secrets    # Secrets detection only
securedx scan --lint       # Security linting only
securedx scan --deps       # Dependency audit only
securedx scan --sast       # SAST deep analysis
securedx scan --json       # Output in JSON format
securedx scan --sarif      # Output in SARIF format

securedx iac

Scan Infrastructure as Code for security misconfigurations.

securedx iac                            # Scan current directory
securedx iac --path ./infrastructure    # Scan specific path
securedx iac --platform terraform       # Terraform files only
securedx iac --platform kubernetes      # Kubernetes manifests only
securedx iac --platform dockerfile      # Dockerfiles only
securedx iac --platform cloudformation  # CloudFormation templates only
securedx iac --platform ansible         # Ansible playbooks only
securedx iac --compliance CIS           # Filter by CIS Benchmark
securedx iac --compliance SOC2,HIPAA    # Multiple compliance frameworks
securedx iac --severity high            # High severity and above
securedx iac --json                     # JSON output
securedx iac --sarif                    # SARIF output

Supported Platforms:

securedx residency

Analyse data residency and geographic data distribution.

securedx residency                     # Full data residency scan
securedx residency --summary           # Summary output only
securedx residency --type database     # Database endpoints only
securedx residency --type storage      # Storage endpoints only
securedx residency --type api          # API endpoints only
securedx residency --provider aws      # AWS services only
securedx residency --provider azure    # Azure services only
securedx residency --provider gcp      # GCP services only
securedx residency --country US        # Filter by country
securedx residency --risk high         # High risk findings only
securedx residency --json              # JSON output

Detection Categories:

Compliance Features:

• GDPR data residency verification (EU/EEA detection)
• Zambia DPA 2021 cross-border transfer identification
• Unknown jurisdiction flagging
• Adequacy decision verification

securedx sbom

Generate Software Bill of Materials.

securedx sbom                      # Generate CycloneDX SBOM
securedx sbom --format spdx        # Generate SPDX SBOM
securedx sbom -o sbom.json         # Save to specified file
securedx sbom --include-dev        # Include development dependencies
securedx sbom --include-licenses   # Include license text

securedx report

Generate security reports.

securedx report                       # Text report to stdout
securedx report --format html         # HTML report
securedx report --format json         # JSON export
securedx report --output report.html  # Save to file
securedx report --history --days 30   # Include historical trends

securedx hooks

Manage Git hook integration.

securedx hooks --status     # Display hook installation status
securedx hooks --install    # Install Git hooks
securedx hooks --uninstall  # Remove Git hooks

securedx debt

Manage security technical debt registry.

securedx debt --summary          # View debt summary
securedx debt --list             # List all entries
securedx debt --open             # List unresolved entries
securedx debt --resolve <id>     # Mark entry as resolved
securedx debt --accept <id>      # Accept risk for entry
securedx debt --prune            # Remove expired entries

Configuration

SecureDX is configured via securedx.config.json in the project root directory.

Configuration File Structure

{
  "gate": {
    "blockThreshold": 7.0,
    "warnThreshold": 4.0,
    "failOnBlock": true,
    "warnOnly": false
  },
  "scanners": {
    "secrets": {
      "enabled": true,
      "customPatterns": []
    },
    "lint": {
      "enabled": true
    },
    "dependencies": {
      "enabled": true
    },
    "sast": {
      "enabled": true
    }
  },
  "hooks": {
    "preCommit": {
      "enabled": true,
      "scanners": ["secrets", "lint"]
    },
    "prePush": {
      "enabled": true,
      "scanners": ["secrets", "lint", "dependencies"]
    }
  },
  "exclude": [
    "node_modules/**",
    "dist/**",
    "*.min.js"
  ]
}

Severity Thresholds

SecureDX uses CVSS (Common Vulnerability Scoring System) v3.x scores for severity classification.

Environment Variables

Configuration can be overridden via environment variables:

Scanner Modules

Secrets Scanner

Detects hardcoded credentials and sensitive tokens using pattern matching and entropy analysis.

Detection Patterns:

Security Linter

Identifies dangerous code patterns and security anti-patterns.

Detection Rules:

Dependency Scanner

Audits package dependencies against known vulnerability databases.

Supported Package Managers:

SAST Scanner

Deep static analysis for OWASP Top 10 vulnerabilities.

Coverage:

• A01:2021 - Broken Access Control
• A02:2021 - Cryptographic Failures
• A03:2021 - Injection
• A04:2021 - Insecure Design
• A05:2021 - Security Misconfiguration
• A06:2021 - Vulnerable and Outdated Components
• A07:2021 - Identification and Authentication Failures
• A08:2021 - Software and Data Integrity Failures
• A09:2021 - Security Logging and Monitoring Failures
• A10:2021 - Server-Side Request Forgery

Language Support

SecureDX provides language-agnostic security scanning with enhanced support for specific ecosystems.

CI/CD Integration

GitHub Actions

name: Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install SecureDX
        run: npm install -g securedx

      - name: Run security scan
        run: securedx scan --sarif > results.sarif

      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI/CD

security_scan:
  stage: test
  image: node:20
  script:
    - npm install -g securedx
    - securedx scan --sarif > gl-sast-report.json
  artifacts:
    reports:
      sast: gl-sast-report.json
    expire_in: 1 week

Azure DevOps

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Install Node.js'

  - script: npm install -g securedx
    displayName: 'Install SecureDX'

  - script: securedx scan --json > $(Build.ArtifactStagingDirectory)/security-report.json
    displayName: 'Run Security Scan'

  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: '$(Build.ArtifactStagingDirectory)/security-report.json'
      artifactName: 'SecurityReport'

Jenkins Pipeline

pipeline {
    agent {
        docker {
            image 'node:20'
        }
    }
    stages {
        stage('Security Scan') {
            steps {
                sh 'npm install -g securedx'
                sh 'securedx scan --json > security-report.json'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: 'security-report.json'
        }
    }
}

Programmatic API

SecureDX exports its core functionality for programmatic use.

Basic Usage

import {
  evaluateGate,
  secretsScanner,
  lintScanner,
  dependencyScanner,
  sastScanner
} from 'securedx';

async function runSecurityAnalysis(projectPath: string) {
  // Execute scanners
  const secretsFindings = await secretsScanner.scan(projectPath);
  const lintFindings = await lintScanner.scan(projectPath);
  const dependencyFindings = await dependencyScanner.scan(projectPath);

  // Combine findings
  const allFindings = [
    ...secretsFindings,
    ...lintFindings,
    ...dependencyFindings
  ];

  // Evaluate security gate
  const result = evaluateGate(allFindings, {
    blockThreshold: 7.0,
    warnThreshold: 4.0
  });

  return {
    decision: result.decision,  // 'PASS', 'WARN', or 'BLOCK'
    findings: result.findings,
    summary: result.summary
  };
}

Gate Result Interface

interface GateResult {
  decision: 'PASS' | 'WARN' | 'BLOCK';
  findings: Finding[];
  blocked: Finding[];
  warnings: Finding[];
  passed: Finding[];
  summary: string;
  executionTime: number;
  totalFindings: number;
  maxSeverity: number;
  blockThreshold: number;
  warnThreshold: number;
}

Security Model

SecureDX implements a graduated security gate model based on the principle that not all security findings warrant equal response. The system categorises findings into three decision outcomes:

This model enables organisations to:

1. Prevent Critical Issues - Block deployment of high-severity vulnerabilities
2. Maintain Awareness - Warn developers of medium-severity issues without blocking
3. Track Technical Debt - Record low-severity findings for future remediation
4. Configure Risk Tolerance - Adjust thresholds per project or environment

Data Handling

• All scan data is stored locally in .securedx/ directory
• No telemetry or external data transmission by default
• Analytics data never leaves the local filesystem
• Suitable for air-gapped and regulated environments

License

SecureDX is distributed under a proprietary Enterprise License.

Permitted Uses:

• Internal security scanning for code analysis
• Installation on systems owned or controlled by the licensee
• Integration into internal CI/CD pipelines

Restrictions:

• No redistribution, sublicensing, or resale
• No reverse engineering, decompilation, or source code derivation
• No modification or creation of derivative works without written consent

For complete license terms, see the LICENSE.md file included with this distribution.

For licensing enquiries, contact: cephasmorgans@gmail.com

Support

Technical Support: cephasmorgans@gmail.com

Documentation: https://hcsys.co/securedx

Bug Reports: Submit via email with reproduction steps and scan output

Copyright 2025-2026 HERO CONTROL SYSTEMS LTD. All rights reserved.

Lusaka, Zambia