| Release - Latest | Release - Pre | |
|---|---|---|
 |
 ( ) |
 ( ) |
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 and select the correct version.
- 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.
clamav: ClamAV, made by Cisco, is an open source anti virus engine for detecting trojans, viruses, malwares, and other malicious threats.yara: YARA, made by VirusTotal, is a tool aimed at but not limited to help malware researchers to identify and classify malware samples.
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.
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.
- Target Version: >= v2.308.0, &:
- Docker
- Require Permission: N/A
jobs:
job_id:
runs-on: "ubuntu-________"
steps:
- uses: "hugoalh/scan-virus-ghaction@<Tag>"Note
This action also provide editions of each tool:
- ClamAV:
"hugoalh/scan-virus-ghaction/clamav@<Tag>" - YARA:
"hugoalh/scan-virus-ghaction/yara@<Tag>"
Note
All of the inputs are optional; Use this action without any input will default to:
@<Tag>: Scan with the ClamAV official assets./clamav@<Tag>: Scan with the ClamAV official assets./yara@<Tag>: Scan with the YARA unofficial assets.
<Boolean = True> Whether to use ClamAV. When this is False, will ignore inputs:
<Boolean = True> 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.
<RegEx[]> ClamAV unofficial assets to use, by regular expression of names in the ClamAV unofficial assets list, separate each regular expression per line; By default, all of the ClamAV unofficial assets are not in use.
<String> 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.
<RegEx[] = .+> ClamAV custom assets to use, by regular expression of relative paths in the input clamav_customassets_directory, separate each regular expression per line; By default, all of the ClamAV custom assets are in use.
<Boolean = False> Whether to use YARA. When this is False, will ignore inputs:
<RegEx[]> YARA unofficial assets to use, by regular expression of names in the YARA unofficial assets list, separate each regular expression per line; By default, all of the YARA unofficial assets are not in use.
<String> 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.
<RegEx[] = .+> YARA custom assets to use, by regular expression of relative paths in the input yara_customassets_directory, separate each regular expression per line; By default, all of the YARA custom assets are in use.
<Boolean = False> Whether to integrate with Git to perform scan by every commits; Require directory is a Git repository. When this is False, will ignore inputs:
<ScriptBlock> 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:
Param([PSCustomObject]$GitCommitMeta)
<# ... Code for determine ... #>
Return $ResultFor example, to ignore Git commits made by Dependabot, and ignore Git commits made by OctoCat before 2022/01/01:
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.
<Boolean = False> Whether to process Git LFS files.
<UInt64 = 0> Limit on how many Git commits will scan, counting is affected by inputs git_ignores and 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).
<Boolean = False> 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.
<ScriptBlock> 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 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:
Param([PSCustomObject]$ElementPreMeta)
<# ... Code for determine ... #>
Return $ResultFor example, to ignore path node_modules:
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.
<ScriptBlock> 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 is more efficiency. To ignore only by the Git commits, use input 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:
Param([PSCustomObject]$ElementPostMeta)
<# ... Code for determine ... #>
Return $ResultImportant
- 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.
<Boolean = True> Whether to record elements which found virus in the log.
<Boolean = False> 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.
<Boolean = True> Whether to record statistics in the log.
<Boolean = False> 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.
[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.
}[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.
}[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]
}<Boolean> Whether this action correctly finished without non catch issues.
<Boolean> Whether there has element which found virus.
-
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[\\/]')
- GitHub Actions
- PowerShell