https://github.com/h7ml/security-auto-scan
๐ ่ชๅจๆซๆๅๆธ
็ GitHub Actions ไธญ็ๆถๆ workflow ๆไปถ | ๆฅๅฟๅ ๅฏ | API ๆบ่ฝ้่ฏ | ๅคๆ ผๅผๆฅๅ | Webhook ้็ฅ
https://github.com/h7ml/security-auto-scan
automation cicd devops github-actions github-api malware-detection python security security-tools supply-chain vulnerability-scanner workflow
Last synced: 4 months ago
JSON representation
๐ ่ชๅจๆซๆๅๆธ ็ GitHub Actions ไธญ็ๆถๆ workflow ๆไปถ | ๆฅๅฟๅ ๅฏ | API ๆบ่ฝ้่ฏ | ๅคๆ ผๅผๆฅๅ | Webhook ้็ฅ
- Host: GitHub
- URL: https://github.com/h7ml/security-auto-scan
- Owner: h7ml
- License: mit
- Created: 2025-10-07T05:34:45.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-10-07T07:04:21.000Z (4 months ago)
- Last Synced: 2025-10-07T08:23:45.808Z (4 months ago)
- Topics: automation, cicd, devops, github-actions, github-api, malware-detection, python, security, security-tools, supply-chain, vulnerability-scanner, workflow
- Language: Python
- Homepage: https://github.com/marketplace/actions/security-auto-scan
- Size: 33.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: security/reports/.gitkeep
Awesome Lists containing this project
README
# Security Auto Scan Action
[](LICENSE)
[](https://github.com/h7ml/security-auto-scan/releases)
[](https://github.com/marketplace/actions/security-auto-scan)
[](https://github.com/h7ml/security-auto-scan/stargazers)
[](https://github.com/h7ml/security-auto-scan/network/members)
[](https://github.com/h7ml/security-auto-scan/watchers)
[](https://github.com/h7ml/security-auto-scan/issues)
[](https://github.com/h7ml/security-auto-scan/pulls)
[](https://github.com/h7ml/security-auto-scan/actions)
**Automatically scan and clean malicious workflow files in GitHub Actions**
[English](./README.md) | [็ฎไฝไธญๆ](./README_zh-CN.md)
## ๐ Introduction
Security Auto Scan is a GitHub Action that automatically detects and removes malicious workflow files. Features:
- ๐ **Auto Scan** all your repositories (personal + organizations)
- ๐งน **Auto Clean** detected malicious files
- ๐ **Log Masking** automatically hide sensitive information using GitHub Actions `::add-mask::`
- ๐ **Generate Reports** detailed scan and cleanup reports
- ๐จ **Create Issues** automatically create alerts when threats are found
- ๐ข **Webhook Notifications** support Slack/Discord/Teams/DingTalk/Feishu, etc.
- ๐พ **Cache Optimization** avoid duplicate cloning, improve performance by 50-80%
- ๐ก๏ธ **Security First** won't delete important files, won't disable itself
## ๐ฏ Use Cases
### Supply Chain Attack Response
If your GitHub account is compromised, attackers might:
1. Inject malicious workflow files
2. Steal your GitHub Secrets
3. Exfiltrate data through domains like `*.oast.fun`
**This Action helps you clean all infected repositories with one click!**
### Regular Security Scanning
Even without an attack, regular scanning is recommended:
- Auto scan daily (cron: '0 3 * * *')
- Immediate alert on suspicious files
- Protect your code and Secrets
## ๐ Quick Start
### 1. Create Workflow File
Create `.github/workflows/security-scan.yml` in your repository:
```yaml
name: Security Scan
on:
# Auto scan daily at 3 AM
schedule:
- cron: '0 3 * * *'
# Manual trigger
workflow_dispatch:
inputs:
keyword:
description: 'Search keyword'
required: false
default: '.oast.fun'
dry_run:
description: 'Scan only (true/false)'
required: false
default: 'false'
jobs:
security-scan:
runs-on: ubuntu-latest
permissions:
contents: write
actions: write
issues: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Security Auto Scan
uses: h7ml/security-auto-scan@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
keyword: ${{ github.event.inputs.keyword || '.oast.fun' }}
dry-run: ${{ github.event.inputs.dry_run || 'false' }}
create-issue: 'true'
mask-sensitive-data: 'true'
```
### 2. Configure Token
**Option A: Use default GITHUB_TOKEN (Recommended)**
The default `GITHUB_TOKEN` can only access the current repository. To scan all repositories, use Option B.
**Option B: Use Personal Access Token**
1. Visit https://github.com/settings/tokens/new
2. Create Token with permissions:
- โ
`repo` - Full repository access
- โ
`workflow` - Workflow permission
3. Add Token to repository Secrets:
- Settings โ Secrets โ Actions โ New repository secret
- Name: `SECURITY_SCAN_TOKEN`
- Value: Paste your Token
4. Update workflow:
```yaml
with:
github-token: ${{ secrets.SECURITY_SCAN_TOKEN }}
```
### 3. Run Scan
**Auto Run**: Executes daily at 3 AM
**Manual Run**:
1. Go to Actions tab
2. Select "Security Scan"
3. Click "Run workflow"
4. Configure parameters and run
## ๐ Input Parameters
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `github-token` | โ
| - | GitHub Token (requires `repo` and `workflow` permissions) |
| `keyword` | โ | `.oast.fun` | Search keyword (malicious signature) |
| `dry-run` | โ | `false` | Scan-only mode (no cleanup) |
| `create-issue` | โ | `true` | Create Issue when threats found |
| `disable-workflows` | โ | `false` | Disable workflows in infected repositories |
| `mask-sensitive-data` | โ | `true` | Log masking (auto-hide sensitive info) |
| `notification-webhook` | โ | `` | Webhook URL (Slack/Teams/Discord support) |
| `notification-template` | โ | `detailed` | Notification template (`compact` or `detailed`) |
## ๐ค Outputs
| Output | Description |
|--------|-------------|
| `infected-repos` | Number of infected repositories |
| `success-count` | Number of successful cleanups |
| `failed-count` | Number of failed cleanups |
| `report-path` | Scan report path |
### Output Usage Example
```yaml
- name: Security Auto Scan
id: scan
uses: h7ml/security-auto-scan@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Check results
run: |
echo "Found ${{ steps.scan.outputs.infected-repos }} infected repositories"
echo "Cleaned successfully ${{ steps.scan.outputs.success-count }}"
echo "Failed to clean ${{ steps.scan.outputs.failed-count }}"
```
## ๐ Features
### โ
Smart Scanning
- Search all your repositories (personal + organizations)
- Use GitHub Code Search API (fast, precise)
- **Pagination support**: automatically fetch all matching results (up to 1000)
- Exclude specific files (e.g., `security-auto-scan.yml`)
- Won't disable current repository workflows
### ๐งน Auto Cleanup
- Clone infected repositories
- Delete malicious workflow files
- Commit and push cleanup
- Record deletion history
### ๐ Security Features
- **Log Masking**: use GitHub Actions `::add-mask::` to auto-hide sensitive info (Token, URL, etc.)
- **Configuration Toggle**: support enable/disable masking
- **Minimum Privilege**: only requires `repo` and `workflow` permissions
- **Prevent Mis-deletion**: exclusion list, won't delete important files
- **Skip Current Repo**: won't disable self
### ๐ข Notification Integration
- **Webhook Support**: Slack/Discord/Teams/DingTalk/Feishu, etc.
- **Notification Templates**: compact and detailed templates
- **Auto Trigger**: auto send when threats found
- **Flexible Config**: customizable notification content
### ๐ง Error Handling
- Detailed push failure analysis
- Auto retry (pull before push on conflict)
- Record failed repositories and reasons
- Provide manual cleanup guide
### ๐ Performance Optimization
- Cache cloned repositories
- Avoid duplicate cloning
- Speed up by 50-80% on subsequent runs
- Auto clean cache older than 7 days
### ๐ Reports and Notifications
- Generate detailed scan reports
- Auto create alert Issues
- Upload Artifacts (30-day retention)
- Failed repository list and manual cleanup steps
## ๐ก๏ธ Security
### Token Security
- **Minimum Privilege**: only requires `repo` and `workflow` permissions
- **Temporary Token**: recommend 90-day expiration
- **Revoke After Use**: immediately revoke Token after scan
- **Log Masking**: auto-hide Token to prevent leakage
### Data Privacy
- **Local Processing**: all data processed in Actions Runner
- **No Upload**: won't upload your code to third-party services
- **Reports Only**: only commit scan reports, not logs
### Prevent Mis-deletion
- **Exclusion List**: won't delete `security-auto-scan.yml`
- **Skip Current Repo**: won't disable self
- **Scan-only Mode**: support scan before deciding to clean
## ๐ Advanced Usage
See [EXAMPLES.md](./EXAMPLES.md) for more examples:
- Basic example
- Complete configuration
- Scan-only mode
- Multi-keyword scanning
- Webhook notification integration
- Log masking configuration
- Matrix strategy scanning
## ๐๏ธ Technical Architecture
- **Language**: Python 3.11
- **Core Library**: requests
- **Runtime**: GitHub Actions (ubuntu-latest)
- **Cache Mechanism**: `.alcache` directory for cloned repos
- **Log Masking**: GitHub Actions `::add-mask::` workflow command
## ๐ค Contributing
Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md)
## ๐ License
[MIT License](./LICENSE)
## ๐ Acknowledgements
- Inspired by real GitHub Actions supply chain attack incidents
- Thanks to all contributors and user feedback
- Referenced industry security best practices
## ๐ Support
- ๐ [Report Issues](https://github.com/h7ml/security-auto-scan/issues)
- ๐ฌ [Discussions](https://github.com/h7ml/security-auto-scan/discussions)
- ๐ง Email: h7ml@qq.com
## ๐ Related Resources
- [GitHub Actions Security Best Practices](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
- [GitHub Code Scanning](https://docs.github.com/en/code-security/code-scanning)
- [GitHub Secret Scanning](https://docs.github.com/en/code-security/secret-scanning)
---
**If this Action helps you, please give it a โญ๏ธ Star!**
Made with โค๏ธ by [h7ml](https://github.com/h7ml)