Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hugoalh/scan-virus-ghaction
A GitHub Action to scan virus (including malicious file and malware).
https://github.com/hugoalh/scan-virus-ghaction
anti-malware anti-virus antivirus gh-action ghaction github-action scan
Last synced: about 1 month ago
JSON representation
A GitHub Action to scan virus (including malicious file and malware).
- Host: GitHub
- URL: https://github.com/hugoalh/scan-virus-ghaction
- Owner: hugoalh
- License: other
- Created: 2021-11-22T10:11:15.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-27T00:47:08.000Z (2 months ago)
- Last Synced: 2024-11-08T05:17:05.429Z (about 2 months ago)
- Topics: anti-malware, anti-virus, antivirus, gh-action, ghaction, github-action, scan
- Language: PowerShell
- Homepage:
- Size: 16.9 MB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Scan Virus (GitHub Action)
[⚖️ MIT](./LICENSE.md)
| | **Release - Latest** | **Release - Pre** |
|:-:|:-:|:-:|
| [](https://github.com/hugoalh/scan-virus-ghaction) |  () |  () |
A GitHub Action to scan virus (including malicious file and malware).
> [!IMPORTANT]
> This documentation is v0.20.0 based; To view other version's documentation, please visit the [versions list](https://github.com/hugoalh/scan-virus-ghaction/tags) and select the correct version.
## 🌟 Feature
- 4\~96% faster than other GitHub Actions with the same purpose, especially when need to perform scan with multiple sessions.
- Ability to ignore specify paths, rules, sessions, and/or signatures.
- Ability to scan by every Git commits.
- Ability to use custom assets.
- Bundle with some of the communities' unofficial rules and signatures.
## 🛡️ Tools
- **`clamav`:** [ClamAV](https://www.clamav.net), made by [Cisco](https://www.cisco.com), is an open source anti virus engine for detecting trojans, viruses, malwares, and other malicious threats.
- **`yara`:** [YARA](http://virustotal.github.io/yara), made by [VirusTotal](https://www.virustotal.com), is a tool aimed at but not limited to help malware researchers to identify and classify malware samples.
### Unofficial Assets
Some of the communities have publicly published unofficial ClamAV and/or YARA assets for free. In order to adoptable, compatible, and usable with this action, these unofficial assets are stored in another repository [hugoalh/scan-virus-ghaction-assets](https://github.com/hugoalh/scan-virus-ghaction-assets).
## ⚠️ Disclaimer
This does not provide any guarantee that carefully hidden objects will be scanned. Strong endpoint security, access, and code review policies and practices are the most effective way to ensure that malicious files and/or codes are not introduced. False positives maybe also will be happened.
## 🔰 Begin
### GitHub Actions
- **Target Version:** >= v2.308.0, &:
- Docker
- **Require Permission:** *N/A*
```yml
jobs:
job_id:
runs-on: "ubuntu-________"
steps:
- uses: "hugoalh/scan-virus-ghaction@"
```
> [!NOTE]
> This action also provide editions of each tool:
>
> - **ClamAV:** `"hugoalh/scan-virus-ghaction/clamav@"`
> - **YARA:** `"hugoalh/scan-virus-ghaction/yara@"`
## 🧩 Input
> [!NOTE]
> All of the inputs are optional; Use this action without any input will default to:
>
> - **`@`:** Scan with the ClamAV official assets.
> - **`/clamav@`:** Scan with the ClamAV official assets.
> - **`/yara@`:** Scan with the YARA unofficial assets.
### `clamav_enable`
`` Whether to use ClamAV. When this is `False`, will ignore inputs:
- [`clamav_update`](#clamav_update)
- [`clamav_unofficialassets_use`](#clamav_unofficialassets_use)
- [`clamav_customassets_directory`](#clamav_customassets_directory)
- [`clamav_customassets_use`](#clamav_customassets_use)
### `clamav_update`
`` Whether to update the ClamAV official assets before scan anything.
> [!IMPORTANT]
> It is recommended to keep this enable to have the latest ClamAV official assets.
### `clamav_unofficialassets_use`
`` ClamAV unofficial assets to use, by regular expression of names in the [ClamAV unofficial assets list](https://github.com/hugoalh/scan-virus-ghaction-assets/blob/main/clamav/index.tsv), separate each regular expression per line; By default, all of the ClamAV unofficial assets are not in use.
### `clamav_customassets_directory`
`` ClamAV custom assets absolute directory path, must be a mapped directory/volume (e.g.: `RUNNER_TEMP`). When this is not defined, will ignore input [`clamav_customassets_use`](#clamav_customassets_use).
### `clamav_customassets_use`
`` ClamAV custom assets to use, by regular expression of relative paths in the input [`clamav_customassets_directory`](#clamav_customassets_directory), separate each regular expression per line; By default, all of the ClamAV custom assets are in use.
### `yara_enable`
`` Whether to use YARA. When this is `False`, will ignore inputs:
- [`yara_unofficialassets_use`](#yara_unofficialassets_use)
- [`yara_customassets_directory`](#yara_customassets_directory)
- [`yara_customassets_use`](#yara_customassets_use)
### `yara_unofficialassets_use`
`` YARA unofficial assets to use, by regular expression of names in the [YARA unofficial assets list](https://github.com/hugoalh/scan-virus-ghaction-assets/blob/main/yara/index.tsv), separate each regular expression per line; By default, all of the YARA unofficial assets are not in use.
### `yara_customassets_directory`
`` YARA custom assets absolute directory path, must be a mapped directory/volume (e.g.: `RUNNER_TEMP`). When this is not defined, will ignore input [`yara_customassets_use`](#yara_customassets_use).
### `yara_customassets_use`
`` YARA custom assets to use, by regular expression of relative paths in the input [`yara_customassets_directory`](#yara_customassets_directory), separate each regular expression per line; By default, all of the YARA custom assets are in use.
### `git_integrate`
`` Whether to integrate with Git to perform scan by every commits; Require directory is a Git repository. When this is `False`, will ignore inputs:
- [`git_ignores`](#git_ignores)
- [`git_lfs`](#git_lfs)
- [`git_limit`](#git_limit)
- [`git_reverse`](#git_reverse)
### `git_ignores`
`` Ignores by the Git commits, by PowerShell script block and must return type of `Boolean` (only return `$True` to able ignore). Ignored Git commits will not be scanned.
The script block should use this pattern in order to receive argument [`GitCommitMeta`](#gitcommitmeta):
```ps1
Param([PSCustomObject]$GitCommitMeta)
<# ... Code for determine ... #>
Return $Result
```
For example, to ignore Git commits made by Dependabot, and ignore Git commits made by OctoCat before 2022/01/01:
```yml
git_ignores: |-
Param($GitCommitMeta)
Return (
$GitCommitMeta.AuthorName -imatch '^dependabot' -or
($GitCommitMeta.AuthorDate -lt ([DateTime]::Parse('2022-01-01T00:00:00Z')) -and $GitCommitMeta.AuthorName -imatch '^octocat$')
)
```
> [!IMPORTANT]
> PowerShell script block is extremely powerful, which also able to execute malicious actions, user should always take extra review for this input value.
### `git_lfs`
`` Whether to process Git LFS files.
### `git_limit`
`` Limit on how many Git commits will scan, counting is affected by inputs [`git_ignores`](#git_ignores) and [`git_reverse`](#git_reverse); When this value is `0`, means no limit.
> [!IMPORTANT]
> For actions which run on the GitHub host, it is highly recommended to define this due to the limit of the job execution time (currently is `6 hours`).
### `git_reverse`
`` Whether to reverse the scan order of the Git commits.
- **`False`:** From the newest commit to the oldest commit.
- **`True`:** From the oldest commit to the newest commit.
### `ignores_pre`
`` Ignores by the paths, sessions, and tools before the scan, by PowerShell script block and must return type of `Boolean` (only return `$True` to able ignore).
To ignore only by the Git commits, use input [`git_ignores`](#git_ignores) is more efficiency. To ignore only by the tools, use inputs `*_enable` is more efficiency.
The script block should use this pattern in order to receive argument [`ElementPreMeta`](#elementpremeta):
```ps1
Param([PSCustomObject]$ElementPreMeta)
<# ... Code for determine ... #>
Return $Result
```
For example, to ignore path `node_modules`:
```yml
ignores_pre: |-
Param($ElementPreMeta)
Return ($ElementPreMeta.Path -imatch '^node_modules[\\/]')
```
> [!IMPORTANT]
> PowerShell script block is extremely powerful, which also able to execute malicious actions, user should always take extra review for this input value.
### `ignores_post`
`` Ignores by the paths, sessions, symbols (i.e. rules or signatures), and tools after the scan, by PowerShell script block and must return type of `Boolean` (only return `$True` to able ignore).
To ignore only by the paths and/or sessions, use input [`ignores_pre`](#ignores_pre) is more efficiency. To ignore only by the Git commits, use input [`git_ignores`](#git_ignores) is more efficiency. To ignore only by the tools, use inputs `*_enable` is more efficiency.
The script block should use this pattern in order to receive argument [`ElementPostMeta`](#elementpostmeta):
```ps1
Param([PSCustomObject]$ElementPostMeta)
<# ... Code for determine ... #>
Return $Result
```
> [!IMPORTANT]
> - PowerShell script block is extremely powerful, which also able to execute malicious actions, user should always take extra review for this input value.
> - It is not recommended to ignore any official symbol due to these rarely have false positives in most cases.
### `found_log`
`` Whether to record elements which found virus in the log.
### `found_summary`
`` Whether to record elements which found virus in the step summary.
> [!IMPORTANT]
> If there has many elements which found virus, step summary maybe get truncated and unable to display all of them.
### `statistics_log`
`` Whether to record statistics in the log.
### `statistics_summary`
`` Whether to record statistics in the step summary.
> [!IMPORTANT]
> If there has many elements which found virus, step summary maybe get truncated and unable to display statistics.
## 🧩 Input's Script Block Argument Syntax
### `ElementPreMeta`
```ps1
[PSCustomObject]$ElementPreMeta = @{
Path = [String] # Relative path based on the current working directory without `./` (e.g.: `relative/path/to/file.extension`).
Session = [PSCustomObject]@{
Name = [String] # "Current" or Git commit hash.
GitCommitMeta = $GitCommitMeta -or $Null # Git commit meta, only exists when the session is on a Git commit.
}
Tool = [String] # Tool ID.
}
```
### `ElementPostMeta`
```ps1
[PSCustomObject]$ElementPostMeta = @{
Path = [String] # Relative path based on the current working directory without `./` (e.g.: `relative/path/to/file.extension`).
Session = [PSCustomObject]@{
Name = [String] # "Current" or Git commit hash.
GitCommitMeta = $GitCommitMeta -or $Null # Git commit meta, only exists when the session is on a Git commit.
}
Symbol = [String] # Rule or signature.
Tool = [String] # Tool ID.
}
```
### `GitCommitMeta`
```ps1
[PSCustomObject]$GitCommitMeta = @{
AuthorDate = [DateTime]
AuthorEmail = [String]
AuthorName = [String]
Body = [String]
CommitHash = [String]
CommitterDate = [DateTime]
CommitterEmail = [String]
CommitterName = [String]
Encoding = [String]
Notes = [String]
ParentHashes = [String[]]
ReflogIdentityEmail = [String]
ReflogIdentityName = [String]
ReflogSelector = [String]
ReflogSubject = [String]
Subject = [String]
TreeHash = [String]
}
```
## 🧩 Output
### `finish`
`` Whether this action correctly finished without non catch issues.
### `found`
`` Whether there has element which found virus.
## ✍️ Example
- ```yml
jobs:
job_id:
name: "Scan Virus"
runs-on: "ubuntu-latest"
steps:
- name: "Checkout Repository"
uses: "actions/[email protected]"
with:
fetch-depth: 0
- name: "Scan Repository"
uses: "hugoalh/[email protected]"
with:
git_ignores: |-
Param($GitCommitMeta)
Return (
$GitCommit.AuthorName -imatch '^dependabot' -or
($GitCommit.AuthorDate -lt ([DateTime]::Parse('2022-01-01T00:00:00Z')) -and $GitCommit.AuthorName -imatch '^octocat$')
)
git_limit: 100
ignores_pre: |-
Param($ElementPreMeta)
Return ($Meta.Path -imatch '^node_modules[\\/]')
```
## 📚 Guide
- GitHub Actions
- [Enabling debug logging](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging)
- PowerShell
- [About Script Blocks](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_script_blocks)