behave-zap 0.1.0

Reusable Behave hooks for Selenium + OWASP ZAP integration.

behave-zap

behave-zap is a working Python library that integrates Behave and OWASP ZAP into a single, reusable web testing + DAST execution model.

It is designed for teams that want:

• Functional browser automation and security scanning in the same run
• Per-feature control of active scan targets
• A final consolidated ZAP report with all discovered alerts
• A CI-friendly flow with reference pipeline examples

Why this library

Security scanning is often bolted on after functional testing. behave-zap makes DAST a first-class part of your Behave lifecycle:

• Hook-based orchestration for before_all, after_feature, and after_all
• Chrome-focused web automation primitives for page objects and driver setup
• Feature-level attack-surface segmentation through target mapping
• Final report generation after full test execution

Core architecture

• behave_zap/hooks.py
  • Behave lifecycle integration
  • ZAP initialization, passive/active scan orchestration, final reports
• behave_zap/web.py
  • Chrome WebDriver creation
  • Context + page-object base classes (PageObject, Button, InputText, etc.)
• test/environment.py
  • Thin project adapter that delegates to the library runner

Installation

Install as editable package in this repository:

pip install -e .

Install from a consumer project:

pip install behave-zap

Quick start

1. Configure DAST in test/conf/properties.cfg.
2. Define feature-specific active scan targets using targets_<feature_file_name>.
3. Run ZAP in daemon mode.
4. Execute Behave scenarios (optionally with @dast tag).
5. Collect final reports from test/output/zapreport-final.html and test/output/zapreport-final.xml.

Feature-level target strategy

Active scan targets are configured per feature file:

• targets_login=...
• targets_product=...
• targets_customer_feedback=...

If a feature has no targets_<feature_name> entry, active scan is skipped for that feature. This improves control of attack surface and reduces noisy scans.

CI and pipeline example

Reference workflow examples are provided as documentation (not active GitHub Actions):

• docs/examples/github-workflows/ci_dast.yml

The pipeline example uses the testingsoul action created for this project to annotate PRs from ZAP results:

• https://github.com/testingsoul/zap-annotations
• https://github.com/marketplace/actions/zap-annotations

Documentation

• Test execution guide: docs/test.md
• Full library experience: docs/library-experience.md

Release and Publish

Best practice for public libraries is:

1. Validate locally (build + twine check).
2. Publish to TestPyPI.
3. Create a GitHub Release tag.
4. Publish to PyPI automatically from GitHub Actions (Trusted Publisher/OIDC recommended).

Release checklist

1. Update version in behave_zap/version.py.
2. Add release notes in CHANGELOG.md.
3. Build and validate package:

   python -m build
   python -m twine check dist/*
   

4. Publish to TestPyPI and test install.
5. Create git tag and GitHub Release (for example v0.1.1).
6. Publish to PyPI.

Manual deploy script

Use:

./scripts/deploy.sh --testpypi
./scripts/deploy.sh --pypi

Script path:

• scripts/deploy.sh

Automatic publish workflow (recommended)

Reference-only workflow example:

• docs/examples/github-workflows/publish-pypi-release.yml

This workflow publishes when a GitHub Release is created.