Add folder anatomy (scripts/agent.py + references/api-reference.md) for 648 cybersecurity skills

Complete skill folder anatomy across all cybersecurity skills:
- scripts/agent.py: 80-150 line Python agents using real libraries (impacket,
  boto3, azure-mgmt-*, kubernetes, pefile, yara, scapy, shodan, stix2, etc.)
- references/api-reference.md: real API documentation with method signatures
- LICENSE: MIT license for all skill folders

skills/executing-phishing-simulation-campaign/scripts/agent.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+# For authorized testing in lab/CTF environments only
+"""Phishing simulation campaign agent using requests to interact with GoPhish API."""
+
+import argparse
+import json
+import logging
+import sys
+from datetime import datetime
+from typing import Optional
+
+try:
+    import requests
+except ImportError:
+    sys.exit("requests is required: pip install requests")
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+
+class GoPhishClient:
+    """Client for the GoPhish REST API."""
+
+    def __init__(self, base_url: str, api_key: str, verify_ssl: bool = False):
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+        self.session.headers.update({"Authorization": f"Bearer {api_key}"})
+        self.session.verify = verify_ssl
+
+    def _get(self, endpoint: str) -> dict:
+        resp = self.session.get(f"{self.base_url}/api/{endpoint}")
+        resp.raise_for_status()
+        return resp.json()
+
+    def _post(self, endpoint: str, data: dict) -> dict:
+        resp = self.session.post(f"{self.base_url}/api/{endpoint}", json=data)
+        resp.raise_for_status()
+        return resp.json()
+
+    def create_sending_profile(self, name: str, smtp_from: str, host: str,
+                                username: str, password: str) -> dict:
+        """Create an SMTP sending profile."""
+        payload = {
+            "name": name,
+            "from_address": smtp_from,
+            "host": host,
+            "username": username,
+            "password": password,
+            "ignore_cert_errors": True,
+        }
+        result = self._post("smtp/", payload)
+        logger.info("Created sending profile: %s (id=%s)", name, result.get("id"))
+        return result
+
+    def create_email_template(self, name: str, subject: str, html_body: str,
+                               text_body: str = "") -> dict:
+        """Create a phishing email template with tracking."""
+        payload = {
+            "name": name,
+            "subject": subject,
+            "html": html_body,
+            "text": text_body,
+            "capture_credentials": True,
+            "capture_passwords": True,
+        }
+        result = self._post("templates/", payload)
+        logger.info("Created email template: %s (id=%s)", name, result.get("id"))
+        return result
+
+    def create_landing_page(self, name: str, html: str, capture_creds: bool = True,
+                             redirect_url: str = "") -> dict:
+        """Create a credential harvesting landing page."""
+        payload = {
+            "name": name,
+            "html": html,
+            "capture_credentials": capture_creds,
+            "capture_passwords": True,
+            "redirect_url": redirect_url,
+        }
+        result = self._post("pages/", payload)
+        logger.info("Created landing page: %s (id=%s)", name, result.get("id"))
+        return result
+
+    def import_targets(self, group_name: str, targets: list) -> dict:
+        """Import target email list as a user group."""
+        payload = {
+            "name": group_name,
+            "targets": [{"email": t["email"], "first_name": t.get("first_name", ""),
+                         "last_name": t.get("last_name", ""), "position": t.get("position", "")}
+                        for t in targets],
+        }
+        result = self._post("groups/", payload)
+        logger.info("Created target group '%s' with %d targets", group_name, len(targets))
+        return result
+
+    def launch_campaign(self, name: str, template_id: int, page_id: int,
+                         smtp_id: int, group_ids: list, url: str) -> dict:
+        """Launch the phishing campaign."""
+        payload = {
+            "name": name,
+            "template": {"id": template_id},
+            "page": {"id": page_id},
+            "smtp": {"id": smtp_id},
+            "groups": [{"id": gid} for gid in group_ids],
+            "url": url,
+            "launch_date": datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S+00:00"),
+        }
+        result = self._post("campaigns/", payload)
+        logger.info("Launched campaign '%s' (id=%s)", name, result.get("id"))
+        return result
+
+    def get_campaign_results(self, campaign_id: int) -> dict:
+        """Retrieve campaign results and metrics."""
+        return self._get(f"campaigns/{campaign_id}/results")
+
+    def get_campaign_summary(self, campaign_id: int) -> dict:
+        """Get summary statistics for a campaign."""
+        result = self._get(f"campaigns/{campaign_id}/summary")
+        return result
+
+    def list_campaigns(self) -> list:
+        """List all campaigns."""
+        return self._get("campaigns/")
+
+
+def compute_metrics(results: dict) -> dict:
+    """Compute phishing simulation success metrics from campaign results."""
+    timeline = results.get("timeline", [])
+    total = results.get("stats", {}).get("total", 0)
+    sent = sum(1 for e in timeline if e.get("message") == "Email Sent")
+    opened = sum(1 for e in timeline if e.get("message") == "Email Opened")
+    clicked = sum(1 for e in timeline if e.get("message") == "Clicked Link")
+    submitted = sum(1 for e in timeline if e.get("message") == "Submitted Data")
+    reported = sum(1 for e in timeline if e.get("message") == "Email Reported")
+
+    return {
+        "total_targets": total,
+        "emails_sent": sent,
+        "emails_opened": opened,
+        "links_clicked": clicked,
+        "credentials_submitted": submitted,
+        "reported_to_it": reported,
+        "click_rate": f"{(clicked / total * 100):.1f}%" if total else "0%",
+        "submission_rate": f"{(submitted / total * 100):.1f}%" if total else "0%",
+        "report_rate": f"{(reported / total * 100):.1f}%" if total else "0%",
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Phishing Simulation Campaign Agent")
+    parser.add_argument("--gophish-url", required=True, help="GoPhish server URL")
+    parser.add_argument("--api-key", required=True, help="GoPhish API key")
+    parser.add_argument("--action", choices=["launch", "results", "list"], default="list")
+    parser.add_argument("--campaign-id", type=int, help="Campaign ID for results")
+    parser.add_argument("--output", default="phishing_report.json")
+    args = parser.parse_args()
+
+    client = GoPhishClient(args.gophish_url, args.api_key)
+
+    if args.action == "list":
+        campaigns = client.list_campaigns()
+        print(json.dumps(campaigns, indent=2, default=str))
+    elif args.action == "results" and args.campaign_id:
+        results = client.get_campaign_results(args.campaign_id)
+        metrics = compute_metrics(results)
+        with open(args.output, "w") as f:
+            json.dump(metrics, f, indent=2)
+        logger.info("Metrics saved to %s", args.output)
+        print(json.dumps(metrics, indent=2))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()