rules: Add more reference URLs (chainguard-dev#157)

* rules: Add more reference URLs

* update testdata

rules/compression/gzip.yara

@@ -1,7 +1,7 @@
-
 rule gzip {
 	meta:
-		description = "Works with gzip files"
+		description = "works with gzip files"
+		ref = "https://www.gnu.org/software/gzip/"
 	strings:
 		$ref = "gzip" fullword
 	condition:

rules/device/pseudo_terminal.yara

@@ -2,6 +2,7 @@
 rule pty : notable {
 	meta:
 		description = "pseudo-terminal access functions"
+		ref = "https://man7.org/linux/man-pages/man3/grantpt.3.html"
 	strings:
 		$grantpt = "grantpt" fullword
 		$ptsname = "ptsname" fullword
@@ -14,6 +15,7 @@ rule pty : notable {
 rule go_pty : notable {
 	meta:
 		description = "pseudo-terminal access from Go"
+		ref = "https://github.com/creack/pty"
 	strings:
 		$ref = "creack/pty"
 	condition:

rules/env/HOME.yara

@@ -1,6 +1,7 @@
 rule HOME {
   meta:
     description = "Looks up the HOME directory for the current user"
+	ref = "https://man.openbsd.org/login.1#ENVIRONMENT"
   strings:
 	$ref = "HOME" fullword
 	
@@ -12,6 +13,7 @@ rule HOME {
 rule node_HOME {
   meta:
     description = "Looks up the HOME directory for the current user"
+	ref = "https://man.openbsd.org/login.1#ENVIRONMENT"
   strings:
 	$ref = "env.HOME" fullword
   condition:

rules/env/SHELL.yara

@@ -1,9 +1,9 @@
 rule SHELL {
   meta:
 	description = "users preferred SHELL path"
+	ref = "https://man.openbsd.org/login.1#ENVIRONMENT"
   strings:
 	$ref = "SHELL" fullword
-//	$getenv = "getenv"
   condition:
 	all of them
 }

rules/env/TERM.yara

@@ -1,6 +1,7 @@
 rule TERM {
   meta:
 	description = "Look up or override terminal settings"
+	ref = "https://www.gnu.org/software/gettext/manual/html_node/The-TERM-variable.html"
   strings:
 	$ref = "TERM" fullword
 //	$getenv = "getenv"

rules/env/USER.yara

@@ -1,6 +1,7 @@
 rule USER {
   meta:
     description = "Looks up the USER name of the current user"
+	ref = "https://man.openbsd.org/login.1#ENVIRONMENT"
   strings:
 	$ref = "USER" fullword
 	$getenv = "getenv"

rules/evasion/amsi_bypass.yara

@@ -2,6 +2,7 @@ rule obfuscated_bypass_amsi : windows suspicious {
   meta:
 	description = "bypass AMSI (Anti-Malware Scan Interface)"
 	author = "Florian Roth"
+	ref = "https://gustavshen.medium.com/bypass-amsi-on-windows-11-75d231b2cac6"
   strings:
 	// extracted from https://github.com/Neo23x0/god-mode-rules/blob/master/godmode.yar
     $amsi_base64 = "AmsiScanBuffer" ascii wide base64

rules/evasion/base64-decode.yara

@@ -1,6 +1,7 @@
 rule base64_decode : notable python {
   meta:
 	description = "decode base64 strings"
+	ref = "https://docs.python.org/3/library/base64.html"
   strings:
 	$b64decode = "b64decode"
   condition:
@@ -10,6 +11,7 @@ rule base64_decode : notable python {
 rule urlsafe_decode64 : notable ruby {
   meta:
 	description = "decode base64 strings"
+	ref = "https://ruby-doc.org/3.3.0/stdlibs/base64/Base64.html"
   strings:
 	$urlsafe_decode64_ruby = "urlsafe_decode64"
   condition:
@@ -19,6 +21,7 @@ rule urlsafe_decode64 : notable ruby {
 rule powershell_decode : notable {
   meta:
 	description = "decode base64 strings"
+	ref = "https://learn.microsoft.com/en-us/dotnet/api/system.convert.frombase64string?view=net-8.0"
   strings:
 	$ref = "[System.Convert]::FromBase64String" ascii
   condition:

rules/exec/pipe.yara

@@ -2,6 +2,7 @@ rule popen : notable {
 	meta:
 		description = "launches program and reads its output"
 		syscall = "pipe"
+		ref = "https://linux.die.net/man/3/popen"
 	strings:
 		$_popen = "_popen" fullword
 		$_pclose = "_pclose" fullword

rules/exec/program-background.yara

@@ -1,6 +1,7 @@
 rule waitpid {
 	meta:
 		description = "wait for process to exit"
+		ref = "https://linux.die.net/man/2/waitpid"
 	strings:
 		$ref = "waitpid" fullword
 	condition:

rules/exec/program.yara

@@ -58,7 +58,8 @@ rule subprocess : notable {
 	meta:
 		syscall = "execve"
 		pledge = "exec"
-		description = "executes external programs"
+		description = "execute external program"
+		ref = "https://man7.org/linux/man-pages/man2/execve.2.html"
 	strings:
 		$naked = "subprocess"
 		$val = /subprocess\.\w{1,16}[\(\"\/\w\'\.\- \,\[\]]{0,64}/
@@ -72,6 +73,7 @@ rule posix_spawn : notable {
 		syscall = "posix_spawn"
 		pledge = "exec"
 		description = "spawn a process"
+		ref = "https://man7.org/linux/man-pages/man3/posix_spawn.3.html"
 	strings:
 		$ref = "posix_spawn"
 	condition:
@@ -83,7 +85,8 @@ rule go_exec : notable {
 	meta:
 		syscall = "posix_spawn"
 		pledge = "exec"
-		description = "spawn a process"
+		description = "run external command"
+		ref = "https://pkg.go.dev/os/exec"
 	strings:
 		$ref = "exec_unix.go"
 	condition:
@@ -95,6 +98,7 @@ rule npm_exec : notable {
 		syscall = "posix_spawn"
 		pledge = "exec"
 		description = "spawn a process"
+		ref = "https://nodejs.org/api/child_process.html"
 	strings:
 		$child = "child_process"
 		$ref_val = /exec\([\'\"][\w \/\'\)]{0,64}/

rules/exec/shell_echo.yara

@@ -2,7 +2,8 @@ rule elf_calls_shell_echo : notable {
 	meta:
 		syscall = "posix_spawn"
 		pledge = "exec"
-		description = "uses the echo command to generate output"
+		description = "program generates text with echo command"
+		ref = "https://linux.die.net/man/1/echo"
 	strings:
 		$val = /echo ['"%\w\>\/ \.]{1,64}/
 		$not_echo = "not echo"

rules/fd/access.yara

@@ -2,6 +2,7 @@ rule bsd_streams : harmless {
 	meta:
 		description = "Access file descriptors"
 		pledge = "stdio"
+		ref = "https://man7.org/linux/man-pages/man2/access.2.html"
 	strings:
 		$_fclose = "_fclose"
 		$_fflush = "_fflush"

rules/fs/directory-create.yara

@@ -2,6 +2,7 @@ rule mkdir {
 	meta:
 		description = "creates directories"
 		pledge = "wpath"
+		ref = "https://man7.org/linux/man-pages/man2/mkdir.2.html"
 	strings:
 		$mkdir = "mkdir" fullword
 	condition:

rules/fs/file-delete.yara

@@ -1,17 +1,16 @@
-
 rule unlink {
 	meta:
 		pledge = "wpath"
 		syscall = "unlink"
 		description = "deletes files"
+		ref = "https://man7.org/linux/man-pages/man2/unlink.2.html"
 	strings:
 		$unlink = "unlink" fullword
 		$unlinkat = "unlinkat" fullword
 	condition:
 		any of them
 }
 
-
 rule rm_f_hardcoded_tmp_path : suspicious {
   meta:
     hash_2023_Backdoors_Backdoor_Linux = "0e08cfb2d92b67ad67e7014e2e91849be3ef1b13c201b7ae928a1bab5a010b5b"
@@ -22,6 +21,7 @@ rule rm_f_hardcoded_tmp_path : suspicious {
     hash_2023_Mirai_Family_Mirai_Linux_yakuza = "c8175e88ccf35532184c42506c99dde75d582e276fa7c2fd46dccbf7e640e278"
     hash_2023_Perl_Backdoor_Perl_Dompu = "f17b6917b835603ef24ab6926d938cbdefbfb537d43fa11965f2e2fdaf80faf6"
     hash_2023_Downloads_6e35 = "6e35b5670953b6ab15e3eb062b8a594d58936dd93ca382bbb3ebdbf076a1f83b"
+	ref = "https://attack.mitre.org/techniques/T1485/"
   strings:
     $ref = /rm +\-[a-zA-Z]{,1}f[a-zA-Z]{,1} \/(tmp|var|dev)\/[\w\/\.\-\%]{0,64}/
 	$not_apt = "/var/lib/apt/lists"

rules/fs/file-flags-change.yara

@@ -1,6 +1,7 @@
 rule chflags {
 	meta:	
 		description = "May update file flags using chflags"
+		ref = "https://man.freebsd.org/cgi/man.cgi?chflags(1)"
 	strings:
 		$chflags = "chflags" fullword
 	condition:

rules/fs/file-open-by_handle.yara

@@ -4,6 +4,7 @@ rule by_handle {
 		syscall = "open_by_handle_at"
 		capability = "CAP_DAC_READ_SEARCH"
 		description = "obtain handle for a pathname and open file via a handle"
+		ref = "https://man7.org/linux/man-pages/man2/open_by_handle_at.2.html"
 	strings:
 		$ref = "name_to_handle_at" fullword
 		$ref2 = "open_by_handle_at" fullword

rules/fs/file-permissions-setuid.yara

@@ -6,6 +6,7 @@ rule make_setuid {
     hash_2023_OrBit_f161 = "f1612924814ac73339f777b48b0de28b716d606e142d4d3f4308ec648e3f56c8"
     hash_2023_Backdoors_Backdoor_Linux_Galore_11 = "5320a828ceff981ca08b671b8f1b6da78aed7b6e1e247a2d32f3ae555a58bc2b"
     hash_2023_Perl_Backdoor_Perl_Galore = "e20fb8f5899b747bcf1bc67b5fbb0e64ea2af24c676f8337f20e7aa17b1d24af"
+	ref = "https://en.wikipedia.org/wiki/Setuid"
   strings:
     $chmod_47 = "chmod 47"
     $chmod_s = "chmod +s"

rules/fs/link-read.yara

@@ -3,6 +3,7 @@ rule readlink {
 		syscall = "readlink"
 		description = "read value of a symbolic link"
 		pledge = "rpath"
+		ref = "https://man7.org/linux/man-pages/man2/readlink.2.html"
 	strings:
 		$ref = "readlink" fullword
 		$ref2 = "readlinkat" fullword

rules/fs/permission-modify.yara

@@ -3,6 +3,7 @@ rule chmod : notable {
 		description = "modifies file permissions"
 		pledge = "fattr"
 		syscall = "chmod"
+		ref = "https://linux.die.net/man/1/chmod"
 	strings:
 		$chmod = "chmod" fullword
 		$dotChmod = "Chmod" fullword
@@ -17,6 +18,7 @@ rule fchmod : notamble {
 		description = "modifies file permissions"
 		pledge = "fattr"
 		syscall = "fchmodat"
+		ref = "https://linux.die.net/man/2/fchmodat"
 	strings:
 		$fchmod = "fchmod" fullword
 		$dotfchmod = ".Fchmod" fullword

rules/kernel/hostname-get.yara

@@ -4,6 +4,7 @@ rule gethostname {
 		pledge = "sysctl"
 		syscall = "sysctl"
 		description = "gets the hostname of the machine"
+		ref = "https://man7.org/linux/man-pages/man2/sethostname.2.html"
 	strings:
 		$gethostname = "gethostname"
 		$proc = "/proc/sys/kernel/hostname"

rules/kernel/uname-get.yara

@@ -1,9 +1,10 @@
 
 rule uname : notable {
 	meta:
-		description = "get system identification"
+		description = "system identification (uname)"
 		pledge = "sysctl"
 		syscall = "sysctl"
+		ref = "https://man7.org/linux/man-pages/man1/uname.1.html"
 	strings:
 		$uname = "uname" fullword
 		$uname2 = "syscall.Uname" fullword
@@ -13,18 +14,20 @@ rule uname : notable {
 
 rule os_release : notable {
 	meta:
-		description = "get system identification"
+		description = "operating-system identification"
 		pledge = "sysctl"
 		syscall = "sysctl"
+		ref = "https://developer.apple.com/documentation/os/1524245-os_release"
 	strings:
 		$ref = "os_release" fullword
 	condition:
 		any of them
 }
 
-rule python_uname : notable {
+rule python_platform : notable {
 	meta:
-		description = "get system identification"
+		description = "system platform identification"
+		ref = "https://docs.python.org/3/library/platform.html"
 	strings:
 		$ref = "platform.dist()"
 		$ref2 = "platform.platform()"
@@ -37,6 +40,7 @@ rule python_uname : notable {
 rule npm_uname : notable {
 	meta:
 		description = "get system identification"
+		ref = "https://nodejs.org/api/process.html"
 	strings:
 		$ref = "process.platform"
 		$ref2 = "process.arch"

rules/net/hostname-resolve.yara

@@ -1,14 +1,26 @@
-
 rule gethostbyname {
 	meta:
 		description = "resolves network hosts via name"
 		pledge = "inet"
+		ref = "https://linux.die.net/man/3/gethostbyname"
+	strings:
+		$gethostbyname2 = "gethostbyname" fullword
+	condition:
+		any of them
+}
+
+
+rule gethostbyname2 {
+	meta:
+		description = "resolves network hosts via name"
+		pledge = "inet"
+		ref = "https://linux.die.net/man/3/gethostbyname2"
 	strings:
 		$gethostbyname2 = "gethostbyname2" fullword
-		$gethostbyname = "gethostbyname" fullword
 	condition:
 		any of them
 }
+
 rule cannot_resolve {
 	meta:
 		description = "Resolves network host names"

rules/net/http-cookies.yara

@@ -2,6 +2,7 @@ rule http_cookie : notable {
 	meta:
 		pledge = "inet"
 		description = "Able to access HTTP resources using cookies"
+		ref = "https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies"
 	strings:
 		$Cookie = "Cookie"
 		$HTTP = "HTTP"

rules/net/icmp.yara

@@ -1,14 +1,17 @@
 rule icmp {
 	meta:
 		description = "ICMP (Internet Control Message Protocol), aka ping"
+		ref = "https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol"
 	strings:
 		$ICMP = "ICMP" fullword
-//		$icmp = "icmp" fullword
 	condition:
 		any of them
 }
 
 rule phrases {
+	meta:
+		description = "ICMP (Internet Control Message Protocol), aka ping"
+		ref = "https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol"
 	strings:
 		$echo_request = "Echo Request" fullword
 		$source_quench = "Source Quench" fullword

rules/net/ip-multicast-send.yara

@@ -2,6 +2,7 @@
 rule multicast {
 	meta:
 		description = "send data to multiple nodes simultaneously"
+		ref = "https://en.wikipedia.org/wiki/IP_multicast"
 	strings:
 		$multicast = "multicast" fullword
 	condition:

rules/net/ip-resolve.yara

@@ -2,6 +2,7 @@
 rule gethostbyaddr {
 	meta:
 		description = "resolves network hosts via IP address"
+		ref = "https://linux.die.net/man/3/gethostbyaddr"
 		pledge = "dns"
 	strings:
 		$gethostbyname2 = "gethostbyaddr" fullword

rules/net/ip-string.yara

@@ -1,6 +1,7 @@
 rule inet_ntoa : notable {
 	meta:
 		pledge = "inet"
+		ref = "https://linux.die.net/man/3/inet_ntoa"
 		description = "converts IP address from byte to string"
 	strings:
 		$ref = "inet_ntoa" fullword