Skip to content

williambrady/portfolio-code-scanner

BranchesTags

Repository files navigation

SDLC Code Scanner

Comprehensive security assessment tool for AWS Infrastructure-as-Code

GitHub Action License

SDLC Code Scanner is a Docker-based security scanning platform that orchestrates multiple industry-leading security tools to provide comprehensive analysis of your AWS infrastructure code. It implements a multi-layered security scanning approach covering linting, security policies, dependency vulnerabilities, and secrets detection.

Available as a GitHub Action for seamless CI/CD integration!

Features

Multi-Tool Orchestration

  • 10+ Security Tools integrated in a single container
  • Automated Detection of IaC frameworks (Terraform, CloudFormation, npm, Python)
  • Parallel Execution for faster scan times
  • Finding Deduplication across multiple tools
  • Rule Exclusions for customizable scanning policies
  • Path Exclusions to skip test directories and fixtures

Comprehensive Coverage

Terraform Scanning

  • terraform fmt/validate - Code formatting and syntax validation
  • TFLint - Terraform linting and best practices
  • tfsec - Security scanning for AWS, Azure, GCP resources
  • Checkov - Policy-as-code and compliance scanning
  • Trivy - Vulnerability and misconfiguration detection

CloudFormation Scanning

  • cfn-lint - Template validation and best practices
  • cfn-nag - Security-focused template analysis
  • Checkov - Policy and compliance checking

Python Scanning

  • Bandit - Python code security analysis (SQL injection, weak crypto, etc.)
  • Safety - Dependency vulnerability detection (CVE scanning)
  • Pylint - Code quality and error detection

Additional Scanning

  • Gitleaks - Secrets and credentials detection
  • npm audit - JavaScript/TypeScript dependency vulnerabilities
  • Snyk - Advanced dependency and license scanning

Reporting

  • JSON - Structured data for CI/CD integration
  • HTML - Interactive dashboard with color-coded severity levels
  • Markdown - Documentation-ready format
  • SARIF - GitHub Code Scanning integration (CodeQL compatible)
  • Severity-based Exit Codes - Fail builds on critical/high findings

Quick Start

GitHub Action (Recommended)

The easiest way to use SDLC Code Scanner is as a GitHub Action:

name: Security Scan

on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run SDLC Code Scanner
        uses: crofton-cloud/sdlc-code-scanner@v1
        with:
          scan-path: '.'
          fail-on-severity: 'HIGH'

See GitHub Action Usage for full documentation.

Prerequisites

  • Docker installed and running (for local usage)

Build the Docker Image

docker build -t sdlc-code-scanner:latest .

Or use the pre-built image (if available):

docker pull croftoncloud/sdlc-code-scanner:latest

Basic Usage

Scan a local repository:

docker run --rm \
  -v /path/to/your/repo:/repo:ro \
  -v $(pwd)/reports:/app/reports \
  sdlc-code-scanner:latest \
  scan-local --repo-path /repo

Using the helper script:

./scripts/run-local-scan.sh /path/to/your/repo

Usage

Scan Local Repository

Scan your IaC code for security issues:

docker run --rm \
  -v /path/to/repo:/repo:ro \
  -v $(pwd)/reports:/app/reports \
  sdlc-code-scanner:latest \
  scan-local \
    --repo-path /repo \
    --output-dir /app/reports \
    --format json \
    --format html \
    --format markdown

Helper Script:

./scripts/run-local-scan.sh /path/to/repo [output-dir] [config-file]

List Available Tools

docker run --rm sdlc-code-scanner:latest list-tools

Validate Configuration (Planned)

docker run --rm \
  -v $(pwd)/config:/app/config:ro \
  sdlc-code-scanner:latest \
  validate-config

Note: Full validation is planned for a future release.

Configuration

The tool is configured via config/config.yaml. Key configuration sections:

Tool Enable/Disable

tools:
  terraform:
    enabled: true
    terraform_fmt: true
    tflint: true
    tfsec: true
    checkov: true
    trivy: true

  cloudformation:
    enabled: true
    cfn_lint: true
    cfn_nag: true
    checkov: true

  python:
    enabled: true
    bandit: true   # Python code security
    safety: true   # Dependency vulnerabilities
    pylint: true   # Code quality

  npm:
    enabled: true
    npm_audit: true
    snyk: true

  secrets:
    enabled: true
    gitleaks: true

Rule Exclusions

Exclude specific rules from reporting (false positives, known exceptions):

tools:
  terraform:
    exclude_rules:
      tflint: []
      tfsec: []
      checkov: []
      trivy: ["DS026"]  # Example: Skip HEALTHCHECK for CLI tools

  cloudformation:
    exclude_rules:
      cfn_nag: ["W89"]  # Example: Lambda VPC requirement
      cfn_lint: []
      checkov: []

  python:
    exclude_rules:
      bandit: ["B404", "B603"]  # subprocess usage - safe in scanner tool
      safety: []

Path Exclusions

Exclude directories from scanning:

repository:
  excluded_paths:
    - "tests"
    - "test"
    - "**/fixtures"
    - "node_modules"
    - ".terraform"

Severity Thresholds

severity:
  fail_on: "HIGH"        # Exit with error if findings at this level or above
  report_minimum: "LOW"  # Only report findings at this level or above

Output Configuration

output:
  directory: "/app/reports"
  formats:
    - json
    - html
    - markdown
  verbose: false

Execution Settings

execution:
  parallel: true      # Run scanners in parallel
  max_workers: 4      # Number of parallel workers
  timeout_per_scanner: 600  # Timeout in seconds

Environment Variables

  • CONFIG_PATH - Path to config.yaml (default: /app/config/config.yaml)
  • LOG_LEVEL - Logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • REPO_PATH - Repository path override
  • REPORTS_PATH - Reports output path override

Report Formats

JSON Report

Structured data suitable for CI/CD pipelines and programmatic processing:

{
  "scan_timestamp": "2025-11-17T01:10:55.945707",
  "summary": {
    "total_findings": 47,
    "by_severity": {
      "CRITICAL": 2,
      "HIGH": 16,
      "MEDIUM": 5,
      "LOW": 6,
      "INFO": 18
    },
    "by_tool": {
      "tfsec": 13,
      "checkov": 18,
      "trivy": 13
    }
  },
  "findings": [...]
}

HTML Report

Interactive dashboard with:

  • Summary statistics and metrics
  • Color-coded severity badges
  • Grouped findings by severity
  • Detailed remediation guidance
  • Responsive design

Markdown Report

Documentation-ready format with:

  • Scan summary and statistics
  • Findings organized by severity
  • Code locations and line numbers
  • Remediation recommendations

GitHub Action

SDLC Code Scanner is available as a GitHub Action for seamless CI/CD integration with GitHub Code Scanning support.

Basic Usage

name: Security Scan

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

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run SDLC Code Scanner
        uses: crofton-cloud/sdlc-code-scanner@v1
        with:
          scan-path: '.'
          fail-on-severity: 'HIGH'

Inputs

Input Description Default
scan-path Path to scan (relative to repository root) .
config-path Path to custom config.yaml file ''
output-formats Comma-separated formats: json, html, markdown, sarif json,sarif
fail-on-severity Fail if findings at this level or above (CRITICAL,HIGH,MEDIUM,LOW,INFO,NONE) HIGH
snyk-token Snyk API token for enhanced scanning ''
upload-sarif Upload SARIF results to GitHub Code Scanning true
verbose Enable verbose output false

Outputs

Output Description
findings-count Total number of security findings
critical-count Number of CRITICAL severity findings
high-count Number of HIGH severity findings
medium-count Number of MEDIUM severity findings
low-count Number of LOW severity findings
report-path Path to the generated report directory
sarif-path Path to the SARIF report file
scan-status Scan result status (passed/failed/error)

Full Example with Code Scanning

name: Security Scan

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

permissions:
  contents: read
  security-events: write

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run SDLC Code Scanner
        id: scan
        uses: crofton-cloud/sdlc-code-scanner@v1
        with:
          scan-path: '.'
          output-formats: 'json,html,sarif'
          fail-on-severity: 'HIGH'
          snyk-token: ${{ secrets.SNYK_TOKEN }}

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ${{ steps.scan.outputs.sarif-path }}

      - name: Upload reports as artifact
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-reports
          path: .sdlc-code-scanner-reports/
          retention-days: 30

      - name: Check scan results
        run: |
          echo "Total findings: ${{ steps.scan.outputs.findings-count }}"
          echo "Critical: ${{ steps.scan.outputs.critical-count }}"
          echo "High: ${{ steps.scan.outputs.high-count }}"

Scanning a Subdirectory

- name: Scan only infrastructure directory
  uses: crofton-cloud/sdlc-code-scanner@v1
  with:
    scan-path: 'infrastructure/terraform'
    fail-on-severity: 'MEDIUM'

Using Custom Configuration

- name: Scan with custom config
  uses: crofton-cloud/sdlc-code-scanner@v1
  with:
    config-path: '.github/sdlc-code-scanner-config.yaml'

Don't Fail on Findings

- name: Scan without failing
  uses: crofton-cloud/sdlc-code-scanner@v1
  with:
    fail-on-severity: 'NONE'

Examples

GitLab CI

security-scan:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker run --rm
        -v $CI_PROJECT_DIR:/repo:ro
        -v $CI_PROJECT_DIR/reports:/app/reports
        sdlc-code-scanner:latest
        scan-local --repo-path /repo --format json
  artifacts:
    paths:
      - reports/
    when: always

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: sdlc-code-scanner
        name: SDLC Code Scanner
        entry: ./scripts/run-local-scan.sh
        language: script
        pass_filenames: false

Exit Codes

  • 0 - Scan completed successfully, no issues at or above fail threshold
  • 1 - Scan failed due to error
  • 2 - Scan completed, findings at or above fail threshold detected

Understanding Findings

Severity Levels

Level Description Typical Issues
CRITICAL Immediate security risk Exposed secrets, publicly accessible resources
HIGH Serious security concern Missing encryption, overly permissive access
MEDIUM Security best practice violation Disabled logging, weak configurations
LOW Minor security improvement Outdated patterns, optimization opportunities
INFO Informational Code style, documentation

Common Findings

CRITICAL:

  • Hardcoded secrets (API keys, passwords)
  • Security groups open to 0.0.0.0/0
  • Public S3 buckets

HIGH:

  • Unencrypted storage (S3, EBS, RDS)
  • Missing IMDSv2 on EC2 instances
  • Disabled CloudTrail logging
  • IAM policies with wildcards

MEDIUM:

  • Missing tags
  • Disabled versioning
  • Insecure protocols (HTTP, TLS 1.0)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    SDLC Code Scanner                          │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌─────────────────────────┐          │
│  │   CLI        │─────→│  Repository Detector    │          │
│  └──────────────┘      └─────────────────────────┘          │
│         │                         │                          │
│         ▼                         ▼                          │
│  ┌──────────────────────────────────────────────┐           │
│  │           Scanner Orchestrator                │           │
│  ├──────────────────────────────────────────────┤           │
│  │  ┌──────────────┐  ┌──────────────┐         │           │
│  │  │  Terraform   │  │ CloudFormation│         │           │
│  │  │   Scanner    │  │    Scanner    │         │           │
│  │  └──────────────┘  └──────────────┘         │           │
│  │  ┌──────────────┐  ┌──────────────┐         │           │
│  │  │   Python     │  │   Secrets    │         │           │
│  │  │   Scanner    │  │   Scanner    │         │           │
│  │  └──────────────┘  └──────────────┘         │           │
│  └──────────────────────────────────────────────┘           │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────────────────────────────────────┐           │
│  │        Report Aggregator                      │           │
│  │  • Deduplication                              │           │
│  │  • Normalization                              │           │
│  │  • Severity Analysis                          │           │
│  └──────────────────────────────────────────────┘           │
│         │                                                    │
│         ▼                                                    │
│  ┌────────────┬─────────────┬──────────────┐               │
│  │   JSON     │    HTML     │   Markdown   │               │
│  │ Formatter  │  Formatter  │  Formatter   │               │
│  └────────────┴─────────────┴──────────────┘               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

File Structure

sdlc-code-scanner/
├── .github/
│   └── workflows/
│       ├── ci.yml               # CI workflow for this repo
│       └── example-usage.yml    # Example workflow for users
├── config/
│   └── config.yaml              # Main configuration file
├── src/
│   ├── scanner_base.py          # Base scanner class
│   ├── config_loader.py         # Configuration management
│   ├── repo_detector.py         # Repository type detection
│   ├── report_aggregator.py     # Finding aggregation
│   ├── main.py                  # CLI entry point
│   ├── scanners/
│   │   ├── terraform_scanner.py
│   │   ├── cloudformation_scanner.py
│   │   ├── python_scanner.py
│   │   └── secrets_scanner.py
│   └── formatters/
│       ├── json_formatter.py
│       ├── html_formatter.py
│       ├── markdown_formatter.py
│       └── sarif_formatter.py   # GitHub Code Scanning format
├── scripts/
│   └── run-local-scan.sh        # Helper script for local scans
├── tests/
│   └── fixtures/                # Test data
├── action.yml                   # GitHub Action definition
├── entrypoint.sh                # GitHub Action entrypoint
├── Dockerfile                   # Multi-stage Docker build
├── requirements.txt             # Python dependencies
└── README.md                    # This file

Troubleshooting

Common Issues

"No findings detected" but I know there are issues:

  • Check if the scanner is enabled in config.yaml
  • Verify the repository path is correct
  • Ensure files have proper extensions (.tf, .yaml, etc.)

"Permission denied" errors:

  • Ensure Docker has access to mounted volumes
  • Check file permissions on repository and output directories

Scanners timing out:

  • Increase timeout_per_scanner in config.yaml
  • Run scanners individually to identify slow tools
  • Consider disabling optional scanners

High memory usage:

  • Reduce max_workers in config.yaml
  • Disable parallel execution
  • Scan smaller directory subsets

Development

Adding a New Scanner

  1. Create scanner class in src/scanners/:
from src.scanner_base import ScannerBase, Finding, Severity

class MyScanner(ScannerBase):
    def is_applicable(self, path: str) -> bool:
        # Return True if scanner should run
        pass

    def run(self, path: str) -> List[Finding]:
        # Execute scanner and return findings
        pass

    def parse_output(self, output: str, stderr: str, return_code: int) -> List[Finding]:
        # Parse scanner output
        pass
  1. Add tool installation to Dockerfile
  2. Update src/main.py to include new scanner
  3. Add configuration options to config/config.yaml
  4. Update tests

Running Tests

# Unit tests
pytest tests/

# Integration tests
pytest tests/integration/

# With coverage
pytest --cov=src --cov-report=html

Roadmap

  • Terraform scanning (fmt, validate, TFLint, tfsec, Checkov, Trivy)
  • CloudFormation scanning (cfn-lint, cfn-nag, Checkov)
  • Python scanning (Bandit, Safety, Pylint)
  • npm/Node.js scanning (npm audit, Snyk)
  • Secrets detection (Gitleaks)
  • Multi-format reporting (JSON, HTML, Markdown, SARIF)
  • Rule exclusions
  • Path exclusions
  • GitHub Action
  • SARIF output format (GitHub Code Scanning)
  • CDK scanning
  • Config validation command
  • Custom policy definitions
  • Baseline/suppression files

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the terms specified in LICENSE.

Support

  • Issues: Report bugs or request features via GitHub Issues
  • Documentation: See docs/ for detailed guides
  • CLAUDE.md: For development with Claude Code

Acknowledgments

This tool integrates and orchestrates the following open-source security tools:

Terraform: Terraform, TFLint, tfsec, Trivy, Checkov

CloudFormation: cfn-lint, cfn-nag, Checkov

Python: Bandit, Safety, Pylint

npm/Node.js: npm audit, Snyk

Secrets: Gitleaks

About

Code scanning and security analysis tools

Topics

security portfolio code-scanning sast

Resources

Readme

License

View license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v1.2.2 Latest
Jan 12, 2026
+ 2 releases

Packages

 
 
 

Contributors 4

  •  
  •  
  •  
  •  

Languages