websec-audit/CONTRIBUTING.md

Contributing to websec-audit

Thank you for your interest in contributing to websec-audit!
All contributions are welcome — bug reports, feature requests, documentation improvements, new modules, and code fixes.

---

Table of Contents

• Code of Conduct
• How to Contribute
• Development Guidelines
• Adding a New Module
• Commit Conventions
• Pull Request Process

---

Code of Conduct

By participating in this project, you agree to:

• Be respectful and constructive in all communications
• Only contribute code intended for authorised security testing
• Not submit payloads, exploits, or code designed to harm systems without consent

---

How to Contribute

Reporting Bugs

1. Search existing issues first
2. Open a new issue using the Bug Report template
3. Include: OS version, tool versions, reproduction steps, expected vs actual behaviour

Requesting Features

1. Open an issue using the Feature Request template
2. Describe the use case and expected output clearly

Code Contributions

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USER/websec-audit.git
3. Create a feature branch: git checkout -b feature/your-feature-name
4. Make your changes following the guidelines below
5. Test your changes
6. Commit using conventional commits (see below)
7. Push: git push origin feature/your-feature-name
8. Open a Pull Request against main

---

Development Guidelines

Shell Style

• Target bash 5.0+ — no POSIX-only constraints, but avoid bash 5.1+ exclusive syntax
• Use set -euo pipefail and IFS=$'\n\t' at the top of every script
• Quote all variable expansions: "$var" not $var
• Use [[ ]] for conditions, not [ ]
• Prefer local variables inside functions
• Run shellcheck on your changes before submitting:

  shellcheck -S warning websec-audit.sh
  

Naming Conventions

Item	Convention	Example
Functions	snake_case	module_sqli()
Constants	UPPER_SNAKE	readonly TOOL_VERSION
Global vars	UPPER_SNAKE	OPT_AGGRESSIVE
Local vars	lower_snake	local scan_target
Module flags	MOD_NAME	MOD_SQLI
Option flags	OPT_NAME	OPT_THREADS

Error Handling

• Never silently ignore errors — use || true only when failure is genuinely acceptable
• Use log_warn when a tool is missing; the script must continue
• Use log_error + exit 1 only for unrecoverable conditions (missing required tool, invalid target)
• All findings must go through add_finding() — never write directly to reports

Performance

• Respect OPT_THREADS and OPT_TIMEOUT in all external tool calls
• Use timeout around all network operations
• Avoid unnecessary subshells in tight loops

---

Adding a New Module

1. Add a toggle variable in the global section:

   MOD_MYMODULE=1
   

2. Add a --skip-mymodule argument in parse_args():

   --skip-mymodule) MOD_MYMODULE=0; shift ;;
   

3. Add the --skip-mymodule entry to the help text in print_usage().

4. Write the module function following this template:

   # ─────────────────────────────────────────────────────────────────────────────
   #  MODULE XX — YOUR MODULE NAME
   # ─────────────────────────────────────────────────────────────────────────────
   module_mymodule() {
     [[ $MOD_MYMODULE -eq 0 ]] && return
     log_section "MODULE XX — YOUR MODULE NAME"
   
     local out_dir="${OUTPUT_DIR}/misc"
   
     # Check for optional tools
     if ! has_tool mytool; then
       log_warn "mytool not available — skipping related checks"
     fi
   
     # ... your logic ...
   
     # Register findings
     add_finding "HIGH" "MYMODULE" "Short finding title" \
       "Detailed description of what was found." \
       "evidence string" \
       "Remediation recommendation."
   
     log_info "Module results → $out_dir"
   }
   

5. Call the module in main() after module_cms and before generate_reports.

6. Add the module to the table in README.md.

7. Add an entry to CHANGELOG.md under [Unreleased].

---

Commit Conventions

We use Conventional Commits:

<type>(<scope>): <short description>

[optional body]

[optional footer]

Types

Type	When to use
feat	New feature or module
fix	Bug fix
docs	Documentation only
refactor	Code change that neither fixes a bug nor adds a feature
perf	Performance improvement
test	Adding or updating tests
chore	Build process, dependency updates

Examples

feat(module): add GraphQL introspection detection
fix(ssl): handle certificates with no expiry date gracefully
docs(readme): add Kali Linux installation instructions
refactor(headers): extract cookie analysis into helper function

---

Pull Request Process

1. One PR per feature/fix — keep changes focused and reviewable
2. Update documentation — README, CHANGELOG, and inline comments
3. Describe your PR — fill in the PR template completely
4. Pass shellcheck — zero warnings on websec-audit.sh and install.sh
5. Test manually — run the affected module(s) against a test target (DVWA, HackTheBox, your own lab)

PRs will be reviewed within 5 business days. Feedback will be given constructively.
Once approved, a maintainer will merge it into main.

---

Thank you for helping make websec-audit better! 🔐