Open-source restructure v1.1

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.yml]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,72 @@
+name: Bug Report
+description: Report a bug in Bull
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please fill in the details below.
+
+  - type: input
+    id: version
+    attributes:
+      label: Bull version
+      description: "Output of `bull --version`"
+      placeholder: "BULL v1.0.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Virtualization provider
+      options:
+        - libvirt (KVM)
+        - VirtualBox
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Guest OS
+      options:
+        - Kali Linux
+        - Parrot Security
+    validations:
+      required: true
+
+  - type: textarea
+    id: host
+    attributes:
+      label: Host environment
+      description: "OS, WSL2 or native Linux, bash version"
+      placeholder: "Ubuntu 24.04 on WSL2, bash 5.2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: "Describe the bug and what you expected instead."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: "Minimal steps to trigger the bug."
+      placeholder: |
+        1. Run `sudo bull create test-vm --os kali`
+        2. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: "Paste any error messages or log output."
+      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature. Please describe your idea below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: "What problem does this solve? What workflow does it improve?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: "How should it work? CLI flags, menu options, etc."
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: "Any other approaches you thought about."

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Checklist
+
+- [ ] `bash -n` passes on all modified `.sh` files
+- [ ] ShellCheck passes (or warnings are justified and excluded)
+- [ ] Tested on at least one provider (libvirt or VirtualBox)
+- [ ] No credentials, tokens, or secrets in the diff
+- [ ] Updated README/docs if the change affects user-facing behavior

.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  shellcheck:
+    name: ShellCheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ludeeus/action-shellcheck@master
+        env:
+          SHELLCHECK_OPTS: -e SC1091 -e SC2034
+        with:
+          severity: warning
+
+  syntax:
+    name: Bash syntax check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check syntax of all .sh files
+        run: |
+          failed=0
+          while IFS= read -r f; do
+            if ! bash -n "$f" 2>&1; then
+              echo "FAIL: $f"
+              failed=1
+            fi
+          done < <(find . -name '*.sh' -type f)
+          exit $failed
+
+  smoke-test:
+    name: Smoke test (source chain)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify all lib files source correctly
+        run: |
+          export SCRIPT_DIR="$PWD"
+          # Source core first, then each lib — must not error
+          source lib/core.sh
+          source lib/inventory.sh
+          source lib/vagrant.sh
+          source lib/vpn.sh
+          source lib/toolkits.sh
+
+          # Verify key functions exist
+          for fn in log_info log_error validate_vm_name \
+                    inventory_init inventory_add \
+                    create_vm start_vm stop_vm \
+                    configure_vpn detect_vpn_type \
+                    install_toolkit toolkit_save; do
+            if ! declare -F "$fn" > /dev/null; then
+              echo "MISSING: $fn"
+              exit 1
+            fi
+          done
+          echo "All expected functions found."

.gitignore

@@ -58,6 +58,5 @@ shellcheck-report.*
 # WSL shim binaries
 .shim/
 
-# Project documentation
-docs/
-!docs/.gitkeep
+# Claude Code internal files
+CLAUDE.md

CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+This project adopts the **Contributor Covenant**, version 2.1.
+The full text is published at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>.
+
+By participating in this project (issues, PRs, discussions) you agree
+to abide by its terms.
+
+Report concerns to the maintainer via the email on their GitHub profile,
+or privately through GitHub Security Advisories.

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Bull
+
+Thanks for your interest in Bull! This guide covers local setup, code conventions, and the PR checklist.
+
+## Local Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/WhiteMuush/Bull.git
+cd Bull
+
+# Check dependencies
+sudo ./bull.sh init
+
+# Optional: install ShellCheck for local linting
+sudo apt install shellcheck   # Debian/Ubuntu
+brew install shellcheck        # macOS
+```
+
+## Code Conventions
+
+| Rule | Example |
+|------|---------|
+| Shebang | `#!/usr/bin/env bash` |
+| Strict mode | `set -uo pipefail` (no `-e` in interactive code) |
+| Variables | Always quoted: `"${var}"` |
+| Functions | `snake_case`, prefixed by module: `inventory_add` |
+| Globals | `BULL_*` prefix, `UPPER_CASE` |
+| Internal functions | Prefixed with `_`: `_display_step` |
+| Colors | Use `log_info` / `log_error` etc., never raw `echo -e ${RED}` |
+| Guard | Every lib file starts with `[[ -n "${_BULL_<MOD>_LOADED:-}" ]] && return 0` |
+| Language | All code, comments, log messages, and docs in English |
+
+## Adding a New Feature
+
+1. Create a feature branch: `git checkout -b feat/my-feature`
+2. Make your changes in the appropriate `lib/*.sh` file
+3. Run `bash -n` on every modified `.sh` file
+4. Run `shellcheck` if available (CI will catch it either way)
+5. Test with at least one provider (libvirt or VirtualBox)
+6. Open a PR against `main`
+
+For adding a new security tool to the toolkit manager, see [docs/ADDING_A_TOOL.md](docs/ADDING_A_TOOL.md).
+
+## PR Checklist
+
+- [ ] `bash -n` passes on all modified `.sh` files
+- [ ] ShellCheck clean (or justified exclusions)
+- [ ] Tested on at least one provider
+- [ ] No credentials or secrets in the diff
+- [ ] README/docs updated if user-facing behavior changed
+
+## Commit Messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add WireGuard config import
+fix: correct snapshot restore on libvirt
+docs: update ARCHITECTURE diagram
+ci: add bash syntax check job
+chore: update .gitignore
+refactor: extract VPN detection into helper
+```
+
+## Reporting Issues
+
+Use the [bug report template](https://github.com/WhiteMuush/Bull/issues/new?template=bug_report.yml) and include:
+- Bull version (`bull --version`)
+- Provider (libvirt or VirtualBox)
+- Host OS and bash version
+- Steps to reproduce

README.md

@@ -1,4 +1,8 @@
-# Your Pentest VM Toolkit
+# Bull
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/WhiteMuush/Bull/actions/workflows/ci.yml/badge.svg)](https://github.com/WhiteMuush/Bull/actions/workflows/ci.yml)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
 Launch a fully-equipped pentest VM in seconds with pre-installed security tools, VPN protection, and encrypted storage.
 
@@ -96,11 +100,41 @@ Optimize-VHD -Path $vhdx -Mode Full
 ## Commands
 
 ```bash
-sudo ./bull.sh help      # Run as root
-bull help                # After init
+sudo ./bull.sh           # Interactive TUI menu
+sudo ./bull.sh help      # CLI help
+sudo ./bull.sh create my-vm --os kali --ram 4096 --cpu 2
+sudo ./bull.sh start my-vm
+sudo ./bull.sh connect my-vm
+sudo ./bull.sh snapshot my-vm pre-exploit
+sudo ./bull.sh vpn my-vm ~/vpn/config.ovpn
+sudo ./bull.sh destroy my-vm
 ```
 
+After running `bull init`, you can use the `bull` alias directly.
+
+## Project Layout
+
+```
+bull.sh              Entry point (TUI + CLI)
+lib/
+  core.sh            Colors, logging, dependency checks, GPG encryption
+  inventory.sh       VM inventory CRUD (JSON via jq)
+  vagrant.sh         Vagrant/libvirt VM lifecycle
+  vpn.sh             VPN configuration + kill switch
+  toolkits.sh        Security toolkit installation + registry
+configs/
+  Vagrantfile.template
+  kali-provision.sh
+  parrot-provision.sh
+docs/
+  ARCHITECTURE.md    Internal design documentation
+  ADDING_A_TOOL.md   How to add tools to the toolkit manager
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and PR checklist.
 
-## Licence
+## License
 
-[**MIT**](https://github.com/WhiteMuush/Bull/blob/master/LICENSE)
+[MIT](LICENSE)

SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+## Scope
+
+Bull is a **wrapper** that orchestrates Vagrant, VirtualBox/libvirt, and
+provisioning scripts. Security reports should concern vulnerabilities in
+Bull itself (e.g., command injection via toolkit URLs, credential leaks,
+privilege escalation in the wrapper logic).
+
+Vulnerabilities in the underlying tools (Vagrant, VirtualBox, libvirt,
+Kali, Parrot) should be reported to their respective maintainers.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x     | Yes       |
+
+## Reporting a Vulnerability
+
+**Do not open a public issue for security vulnerabilities.**
+
+Instead, use one of:
+
+1. **GitHub Security Advisories** (preferred):
+   Go to [Security > Advisories](https://github.com/WhiteMuush/Bull/security/advisories)
+   and click "Report a vulnerability".
+
+2. **Email**: Contact the maintainer via the email on their
+   [GitHub profile](https://github.com/WhiteMuush).
+
+You should receive an acknowledgment within 48 hours. A fix or mitigation
+will be coordinated privately before any public disclosure.
+
+## Security Design
+
+- Passwords are encrypted with GPG (AES256 + SHA512, 65M iterations)
+- VM credentials are never stored in plaintext
+- `/home` is encrypted with ecryptfs inside VMs
+- Default OS accounts are locked after provisioning
+- Synced folders are disabled (no host filesystem exposure)
+- Toolkit URLs are validated against shell metacharacters before SSH execution
+- VPN kill switch blocks all non-VPN traffic via iptables