Package for PyPI: structure, release docs, and CI (#11, #12, #13)

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+      - name: Run tests
+        run: pytest -q
+      - name: Smoke-test entry points
+        run: |
+          domain-analyzer --version
+          domain-analyzer --help
+          python -m domain_security_analyzer --version
+
+  build:
+    name: build & metadata check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Build distributions and validate metadata
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*

.gitignore

@@ -1,2 +1,8 @@
 __pycache__/
 *.pyc
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+*.egg

AUTHORS.md

@@ -0,0 +1,9 @@
+# Authors
+
+Domain Security Analyzer is created and maintained by:
+
+- CallMarcus (<https://github.com/CallMarcus>)
+
+Thanks also to everyone who has contributed bug reports, ideas, and code. See the
+[contributors graph](https://github.com/CallMarcus/domain-security-analyzer/graphs/contributors)
+for the full list.

CHANGELOG.md

@@ -1,12 +1,44 @@
 # Changelog
 
-All notable changes to this project will be documented here.
+All notable changes to this project are documented here.
 
-## Unreleased
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-- Subdomain discovery: filter out hosts that resolve solely due to wildcard DNS by comparing against A and CNAME baselines.
-- Add CLI flag `--include-wildcard-matches` to include wildcard-matched subdomains when desired.
-- Add CLI flag `--filtered-subdomains-file <path>` to export filtered subdomains per domain to a separate CSV.
-- Update README and docs with a Wildcard Filtering note and flag usage.
-- Add `scripts/test_wildcard_filtering.py` mock-based test harness demonstrating the filtering behavior.
+## [Unreleased]
 
+## [1.0.0] - 2026-06-21
+
+First packaged release, distributable via PyPI.
+
+### Added
+
+- **Packaging**: project is now an installable Python package
+  (`pip install domain-security-analyzer`) with a `pyproject.toml`, a
+  `domain-analyzer` console entry point, `python -m domain_security_analyzer`
+  module execution, and an importable API
+  (`from domain_security_analyzer import DomainAnalyzer`).
+- **Subresource Integrity (SRI) scanning**: detects external JS/CSS resources,
+  computes SRI coverage, identifies SHA-256/384/512 usage, and reports gaps in
+  the CSV output. Standalone `scripts/sri_parser.py` crawler mirrors
+  SecurityScorecard's "Unsafe SRI" guidance.
+- **Wildcard subdomain filtering**: suppresses subdomains that resolve solely due
+  to wildcard DNS by comparing against A and CNAME baselines.
+- CLI flag `--include-wildcard-matches` to include wildcard-matched subdomains.
+- CLI flag `--filtered-subdomains-file <path>` to export filtered subdomains per
+  domain to a separate CSV.
+- `scripts/test_wildcard_filtering.py` mock-based test harness demonstrating the
+  filtering behavior.
+- Reference documentation for SRI, CSV output, SPF, DKIM, and DMARC under
+  `docs/`.
+
+### Changed
+
+- Core logic moved from the top-level `domain_analyzer.py` script into the
+  `domain_security_analyzer` package. `domain_analyzer.py` is retained as a thin
+  backward-compatible shim, so `python domain_analyzer.py ...` and
+  `from domain_analyzer import DomainAnalyzer` continue to work.
+- README and docs updated with a Wildcard Filtering note and flag usage.
+
+[Unreleased]: https://github.com/CallMarcus/domain-security-analyzer/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/CallMarcus/domain-security-analyzer/releases/tag/v1.0.0

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for your interest in improving Domain Security Analyzer! Contributions of
+all kinds are welcome — bug reports, feature ideas, documentation, and code.
+
+## Getting started
+
+1. Fork the repository and clone your fork.
+2. Create a development environment and install the package in editable mode:
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate    # Windows: .venv\Scripts\activate
+   pip install -e .
+   ```
+
+3. Create a branch for your change:
+
+   ```bash
+   git checkout -b my-feature
+   ```
+
+## Project layout
+
+- `domain_security_analyzer/` — the installable package
+  - `analyzer.py` — core analysis logic (`DomainAnalyzer`, `analyze_domains_from_file`)
+  - `cli.py` — command-line interface (`domain-analyzer` entry point)
+- `domain_analyzer.py` — thin backward-compatible shim for the legacy script path
+- `scripts/` — standalone helpers (`sri_parser.py`, `parked_domain_csv.py`, test harnesses)
+- `docs/` — reference guides (SRI, CSV output, SPF, DKIM, DMARC)
+
+## Making changes
+
+- Keep changes focused and match the style of the surrounding code.
+- Update `README.md` and the relevant files in `docs/` when behavior changes.
+- Add an entry under the `## [Unreleased]` section of `CHANGELOG.md`.
+- Verify the package still builds and the CLI works:
+
+  ```bash
+  pip install -e .
+  domain-analyzer --help
+  python -m build && twine check dist/*
+  ```
+
+## Submitting
+
+1. Push your branch and open a pull request against `main`.
+2. Describe what the change does and why, and link any related issues.
+3. Make sure the description notes any new dependencies or CLI flags.
+
+## Reporting issues
+
+Open an issue at
+<https://github.com/CallMarcus/domain-security-analyzer/issues> with steps to
+reproduce, the command you ran, and the observed vs. expected behavior.

MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include AUTHORS.md
+include requirements.txt
+recursive-include docs *.md
+recursive-include examples *
+include scripts/*.py

README.md

@@ -1,5 +1,10 @@
 # Domain Security Analyzer
 
+[![PyPI version](https://img.shields.io/pypi/v/domain-security-analyzer.svg)](https://pypi.org/project/domain-security-analyzer/)
+[![Python versions](https://img.shields.io/pypi/pyversions/domain-security-analyzer.svg)](https://pypi.org/project/domain-security-analyzer/)
+[![Downloads](https://img.shields.io/pypi/dm/domain-security-analyzer.svg)](https://pypi.org/project/domain-security-analyzer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 A comprehensive Python tool for analyzing domain security configurations including DNS records, email security policies, subdomain discovery, and **Subresource Integrity (SRI) scanning**. The tool performs parallel analysis of domain portfolios to identify potential security configuration issues and modern security compliance gaps.
 
 ## Features
@@ -39,6 +44,25 @@ A comprehensive Python tool for analyzing domain security configurations includi
 
 ### **Installation**
 
+Install from PyPI (recommended):
+
+```bash
+pip install domain-security-analyzer
+```
+
+This installs the dependencies automatically and adds the `domain-analyzer`
+command to your `PATH`.
+
+#### From source
+
+```bash
+git clone https://github.com/CallMarcus/domain-security-analyzer.git
+cd domain-security-analyzer
+pip install -e .
+```
+
+#### Dependencies only (running the script directly)
+
 ```bash
 # Install required dependencies
 pip install dnspython requests beautifulsoup4
@@ -47,7 +71,7 @@ pip install dnspython requests beautifulsoup4
 pip install -r requirements.txt
 ```
 
-The script automatically validates dependencies and provides installation guidance:
+When run as a script, the tool automatically validates dependencies and provides installation guidance:
 
 ```bash
 $ python domain_analyzer.py
@@ -72,16 +96,25 @@ contoso.com
 rzy.domain.com
 ```
 
-Run the analyzer and specify the output CSV file:
+Run the analyzer and specify the output CSV file. If installed from PyPI, use the
+`domain-analyzer` command:
 
 ```bash
-python domain_analyzer.py examples/domains.txt report.csv
+domain-analyzer examples/domains.txt report.csv
 ```
 
 You can optionally set the number of parallel workers:
 
 ```bash
-python domain_analyzer.py examples/domains.txt report.csv 20
+domain-analyzer examples/domains.txt report.csv 20
+```
+
+The same interface is available via `python -m domain_security_analyzer` or, for
+backward compatibility, by running the script directly:
+
+```bash
+python -m domain_security_analyzer examples/domains.txt report.csv
+python domain_analyzer.py examples/domains.txt report.csv   # legacy shim
 ```
 
 The generated CSV includes comprehensive security analysis with **29 columns**: