API¶
A full list of supported functions and properties available in GreyScript is contained below.
Global Variables¶
params¶
A list object of command line parameters provided when called from the terminal
Usage Example
Running mycommand --help:
["--help"]
mycommand:
[]
mycommand try out this 1:
["try", "out", "this", "1"]
if params.len == 0 or params[0] == "--help" then
print("usage information about my command")
else
...
params originates from the full parameter string provided in the terminal, separated into an array of strings separated by each space (" ").
System Functions¶
In addition to string, number, list and map functions, there are a small number of native system functions.
globals & locals¶
See scope
print(data)¶
Takes data (optional any) and prints it to the terminal.
If no data is supplied, prints an empty line to the terminal.
Usage Example
print(123)
print("123")
print(range(1, 5))
print({"a":"b"})
print(1==1)
123
123
[1, 2, 3, 4, 5]
{"a":"b"}
1
wait(duration)¶
Pauses the script for the indicated duration (number). If duration is not specified, the default value is 1 second.
time¶
Returns the number of seconds since the program execution began.
Usage Example
print("Begin")
wait(0.2)
print(time)
Begin
0.201
typeof(var)¶
Takes a variable (any)
Returns the type of variable (string). Supported types:
Usage Example
v = 32
w = "thirty two"
x = [3, 2]
y = {32: "thirty two"}
z = function()
//do something
return 1
end function
typeof(v)
typeof(w)
typeof(x)
typeof(y)
typeof(z)
typeof(@z)
number
string
list
map
number
function
Per example z, note that where a variable is a function, and that function returns any data then typeof(var) will return the type of data, because providing the function to typeof actually invokes the function.
It may therefore be advisable to reference a variable when using typeof, as in last line above.
md5(str)¶
Returns the md5 hash (string) of the provided string.
Usage Example
X = 55
print(md5("orange"))
print(md5(str(X)))
fe01d67a002dfa0f3ac084298142eccd
b53b3a3d6ab90ce0268229151c9bde11
get_router(IP)¶
Takes an IP address (string) - lan or public. If no IP is provided, defaults to the user's router
Returns a Router object or null if not found
get_shell(user, password)¶
Returns a Shell object for the shell executing the script
Takes an optional username and password to return a shell for that user
Usage Example
myshell = get_shell
print("Type: " + typeof(myshell))
file = myshell.host_computer.File("/etc/passwd")
print(file.name)
Type: shell
passwd
nslookup(domain)¶
Takes a domain name (string)
Returns string - either the public IP of the provided domain or Not found
whois(IP)¶
Takes a public IP address (string)
Returns a string containing several lines of whois information or No Info available
is_valid_ip(string)¶
Evaluates whether a string is a valid IPv4 address
Takes a string and returns 0 (false) or 1 (true)
Usage Example
tof = function(v)
return ("in" * (v == 0)) + "valid"
end function
print(tof(is_valid_ip("abc")))
print(tof(is_valid_ip("192.168.0.1")))
print(tof(is_valid_ip("192.168.0.99")))
print(tof(is_valid_ip("192.168.0.999")))
invalid
valid
valid
invalid
The third IP above evaluates as true because it conforms to a valid IPv4 format, even if that IP doesn't exist in Grey Hack. The fourth IP fails because it is out of range (0.0.0.0 to 0.255.255.255).
is_lan_ip(string)¶
Evaluates whether a string is a valid LAN IPv4 address (ranging from 192.168.0.0 to 192.168.255.255).
Takes a string and returns 0 (false) or 1 (true)
command_info(ref)¶
Obtain usage information for a native Grey Hack command
Takes a usage string and returns the usage information (string) or "Unknown info"
Usage Example
print(command_info("ftp_usage"))
Usage: ftp [user@password] [ip address]
Example: ftp John@Connor 127.0.0.1
current_date¶
Returns a string with the current date and time on the player's clock
Date/Time Format
In Grey Hack, a date and time strings are in the format d-m-yyyy hh:mm (e.g. 29-4-2017 19:04)
current_path¶
Returns the path (string) to the working directory of the terminal (e.g. /home/bert)
parent_path¶
Takes a file or directory path (string)
Returns the path to the parent directory (string)
Usage Example
print(parent_path("/etc/passwd"))
print(parent_path(current_path))
print(parent_path("/"))
/etc
/home/user
/
Note the returned path does not have a trailing slash.
home_dir¶
Returns the path (string) to the active user's home directory (e.g. /home/username)
program_path¶
Returns the absolute path (string) to the executing script (e.g. /bin/myprogram)
active_user¶
Returns the username of the active user (string)
user_mail_address¶
Returns the email address (string) of the active user, or null if they do not have an email address
user_bank_number¶
Returns the bank account number (int) of the active user, or null if they do not have a bank account
format_columns(str)¶
Returns string data formatted into columns (such as for use in the nmap command)
Rows should be separated by a new line, while columns are separated by a space. See the below example.
Usage Example
data = "COL1 COL2 COL3" //define our column titles
data = data + "\none two three" //define our data, each column data separated by a space
data = data + "\nthing1 thing2 thing3" //add another row
print(format_columns(data))
COL 1 COL2 COL3
one two three
thing1 thing2 thing3
user_input(msg, isPassword)¶
Requests the user's input, along with an optional message and password mask (int 0 or 1), and returns the input to a variable
If isPassword is provided and is 1 then the user's input will be masked in the terminal (e.g. ******* instead of machina)
Usage Example
name = user_input("What is your name?")
print("Hello " + name + "!")
string) will be returned as the declared variable (in this case name).
include_lib(libpath)¶
Includes an external library on the executing machine, specified by its file path (string). Libraries contain their own methods, and operate as custom objects.
Returns a Metaxploit object that corresponds to the provided library, or null on failure
Usage Example
cryptools = include_lib("/lib/crypto.so") //providing /lib/crypto.so exists, returns the crypto object
if not cryptools then exit("Error: Missing crypto library") //error handling
print(cryptools.decipher("/etc/passwd")) //prints the deciphered root password
bitwise(operator, num1, num2)¶
Manipulate data at the bit level. Bitwise operates on one or more bit patterns or binary numerals at the level of their individual bits.
The operator argument accepts the following operators:
&(Bitwise AND)|(Bitwise OR)^(Bitwise XOR)<<(Left Shift)>>(Right Shift)>>>(Unsigned Right Shift)
Usage Example
result = bitwise("&", 12, 25)
print("Result: " + result)
Result: 8
clear_screen¶
Clears all text from the terminal that is running the script.
This clears ALL output from the terminal, not just output printed from the current script.
exit(msg=null)¶
Exits the script, optionally printing a provided message (string). The script will abort and no further lines of code will be processed
Usage Example
print("Hello")
exit("Script Exited")
print("Goodbye")
Hello
Script Exited
for i in range(1, 10)
print(i)
if i == 5 then exit
end for
print("Something else")
1
2
3
4
5
Objects¶
There are nine objects in the GreyScript API, which contain their own properties and functions:
Router¶
Instantiated by get_router, this object provides the following functions:
public_ip¶
Returns the public IP address (string) of the router
local_ip¶
Returns the LAN IP address (string) of the router
device_ports(IP)¶
Takes a LAN IP address (string)
Returns a list of Port objects for ports used on the corresponding machine
computers_lan_ip¶
Returns a list of IP addresses for machines connected to the router
ping_port(port)¶
Takes an external port number (int)
Returns the Port object for the specified port if forwarding is configured for it; otherwise returns null
port_info(Port)¶
Takes a Port object
Returns service information for that port (string)
used_ports¶
Returns a list of Port objects - all ports configured for forwarding on the router
bssid_name¶
Returns the mac address (bssid string) of the router
essid_name¶
Returns the name (essid string) of the router
Computer¶
Computer is instantiated by Shell.host_computer and provides the following functions:
change_password(user, password)¶
Changes an existing user's password. Takes a user (string) and password (string).
Returns 1 on success, or error string on failure
Root Only
This function can only be executed when the script is executed by the root user.
create_user(user, password)¶
Creates a new user on the computer. Requires a username (string) and password (string).
Returns 1 on success, or error string on failure
Root Only
This function can only be executed when the script is executed by the root user.
create_group(username, groupname)¶
Creates a group (named with a chosen string) for the named user (string username of an existing user account)
Returns 1 (true) on success or error string on failure
Root Only
This function can only be executed when the script is executed by the root user.
create_folder(path, name)¶
Creates a directory name within path
Returns 1 (true) on success or 0 (false) / null on failure
Usage Example
comp = get_shell.host_computer
comp.create_folder(current_path, "foldername")
close_program(pid)¶
Terminates a process. Takes a process ID (int).
Returns 1 on success, 0 if the process cannot be found, or an error string on failure to terminate the process
connect_wifi(interface, bssid, essid, password)¶
Connects to a wireless network. Takes an interface (string e.g. eth0), bssid (string), essid (string), and password (string)
Returns 1 on successful connection, null if the network cannot be found, or an error string on connection failure
delete_user(user, removeHome)¶
Deletes a user, and optionally deletes their /home/user directory. Requires username (string) and takes an optional removeHome int (1 or 0)
Returns 1 on success, or error string on failure
Root Only
This function can only be executed when the script is executed by the root user.
delete_group(username, groupname)¶
Deletes a group (named string) on the machine, removing it from the named user (string username of an existing user)
Returns 1 (true) on success or error string on failure
Root Only
This function can only be executed when the script is executed by the root user.
Group Deletion is Per User
Deleting a group for a user removes that group from that specific user. This function will not remove any identically titled group from any other user.
groups(username)¶
Returns a line delimited string of all groups a given user (string username) belongs to
network_devices¶
Returns a string with a list of network device(s) on the computer
Usage Example
print(get_shell.host_computer.network_devices)
eth0 85978LM False
The above output shows the network interface (eth0), chipset (85978LM) and whether monitoring is enabled (False).
get_ports¶
Returns a list of Port objects for services running on the computer
is_network_active¶
Does the Computer have internet access?
Returns 1 (true) or 0 (false)
lan_ip¶
Returns the LAN IP (string) of the computer
show_procs¶
Returns a string listing the processes currently running on the machine
Usage Example
print("Current user: " + active_user + "\n\nCurrent processes:")
print(get_shell.host_computer.show_procs)
Current user: bert
Current processes:
USER PID CPU MEM COMMAND
root 9230 0.0% 13.7% kernel_task
root 8709 0.0% 11.2% Xorg
bert 7365 0.0% 14.1% Browser.exe
bert 7399 0.0% 8.6% Terminal.exe
touch(path, filename)¶
Creates an empty file with the name of filename (string) in the chosen directory path (string)
Returns 1 on success, or a string (containing an error) on failure
Usage Example
comp = get_shell.host_computer
comp.touch("/path/to/directory", "filename")
print(comp.File("/path/to/directory/filename").name) // "filename"
wifi_networks(interface)¶
Takes a network interface (string e.g. eth0)
Returns a list object of WiFi networks available to the user's machine.
Usage Example
networks = get_shell.host_computer.wifi_networks("eth0")
for net in networks
print(net.split(" ")[0])
end for
C7:E7:C8:43:9A:E7
3F:65:29:C5:83:AB
FE:50:51:7F:61:47
72:5B:80:A7:77:48
65:61:E4:79:B3:D0
5B:14:B4:D3:B5:BD
Each item in the list contains (space delimited) bssid, signal strength, and essid.
File(path)¶
Obtain a File object for a file on the machine.
Returns a File object or null if the file does not exist
Usage Example
comp = get_shell.host_computer
myfile = comp.File("/path/to/file")
myfile.delete
comp.File("/path/to/directory").delete
Relative path
File() does not require an absolute path.
comp = get_shell.host_computer
bank = comp.File("Config/Bank.txt")
print(bank.content)
If a user runs this from their default terminal (where the working directory will be /home/user), then it will print the contents of their Bank.txt file.
If the user opens terminal but changes directory before running the above script, the relative path won't return a File object and this script will result in errors. Accordingly, you would need to check the file exists or the content is not null before trying to print the file.
File¶
File is typically instantiated by Computer.File and provides the following functions:
Directories
In this documentation, file refers to both files and folders. Folders and files are of course separate, but a file object can represent a directory.
So remember: folders may not be files but a folder is a file. See is_folder below.
copy(path, newname)¶
Copies a file to a new directory path (string) with the provided name (string). Overwrites any existing file with newname.
On success, returns 1 and the terminal outputs the copied file dialogue. On failure, returns either an error (string) such as permission denied or null (if File object not valid).
Usage Example
comp = get_shell.host_computer
comp.File("/etc/passwd").copy(current_path, "passfile")
move(path, newname)¶
Moves a file to the specified path, similar to File.copy, except that the original file is moved.
On success, returns 1. On failure, returns either an error (string) such as permission denied or null (if File object not valid).
Usage Example
get_shell.host_computer.File("/home/user/Downloads").move("/home/user/Desktop", "Downloads")
rename(newname)¶
Renames a file to newname (string)
Returns a string (empty on success, or with an error on failure)
Usage Example
fruit = get_shell.host_computer.File("apple")
if(typeof(fruit) == "file") then
fruit.rename("banana")
end if
chmod(perms, recursive)¶
Modifies the file's permissions
Takes a permissions string (e.g. u+wr) and optional recursive flag (int 0 or 1)
If the file is a folder and the recursive flag is 1, the permissions change will apply recursively, to all the files and folders inside the target folder.
Returns a string (empty on success, or with an error on failure)
Usage Example
comp = get_shell.host_computer
pwd = comp.File("/etc/passwd")
etc = comp.File("/etc")
pwd.chmod("o-wrx") //removes read, write, and execute permissions for guest on the file
etc.chmod("o-wrx", 1) //removes rwx permissions for guest on /etc and all files within /etc
set_content(content)¶
Sets a file's contents to content (string)
Returns 1 on success, or a string (containing an error) on failure
Usage Example
myfile = get_shell.host_computer.File("/etc/passwd")
myfile.set_content("blah") // sets the content of /etc/passwd to "blah"
set_group(group, recursive)¶
Modifies the file's ownership group
Takes the name of a group (string) and optional recursive flag (int 0 or 1)
If the file is a folder and the recursive flag is 1, the ownership change will apply recursively, to all the files and folders inside the target folder.
Root Only
This function can only be executed when the script is executed by the root user.
group¶
Returns the group (string) to whom the file belongs
path¶
Returns the full path (string) to the file or directory.
Usage Example
computer = get_shell.host_computer
file = computer.File("/root/Config/Bank.txt")
print(file.path) // /root/Config/Bank.txt
print(file.parent.path) // /root/Config
content¶
Returns the contents of the file (string)
is_binary¶
Is the file a binary file?
Returns 1 (true) or 0 (false)
Only for files. Returns null if called on a directory
is_folder¶
Is the file a directory?
Returns 1 (true) or 0 (false)
has_permission(p)¶
Does the active user have permission to read, write, or execute the file?
Takes a permission (string: r, w, or x) and returns 1 (true) or 0 (false)
set_owner(owner, recursive)¶
Modifies the file's ownership user
Takes the name of a user (string) and optional recursive flag (int 0 or 1)
If the file is a folder and the recursive flag is 1, the ownership change will apply recursively, to all the files and folders inside the target folder.
Root Only
This function can only be executed when the script is executed by the root user.
owner¶
Returns the username of the file's owner (string)
permissions¶
Returns a string with the permissions set on the file (e.g. -rw-rw-r--)
To set permissions, see chmod
parent¶
Returns the File object of the file's parent directory (or null if the initial object is /)
Usage Example
comp = get_shell.host_computer
print(comp.File("/Public/htdocs/downloads").parent.name)
htdocs
name¶
Returns the name of the file (string)
size¶
Returns the size (int) of the file in bytes
delete¶
Deletes the file and returns a string (empty on success, or with an error on failure)
get_folders¶
Returns a list of File objects for all folders in the target directory
Only for directories. Returns null if called on a file
get_files¶
Returns a list of File objects for all files (excluding folder) in the target directory
Only for directories. Returns null if called on a file
Port¶
Port objects be obtained by Router.ping_port, Router.used_ports, Router.computer_ports or Computer.get_ports, and provide for the following functions:
get_lan_ip¶
Returns the LAN IP Address for which the port forwarding record is configured (string)
is_closed¶
Is the port closed?
Returns 1 (true) or 0 (false)
port_number¶
Returns the port number (int)
Shell¶
Shell objects can be instantiated by get_shell and provide the following functions:
host_computer¶
Returns the shell's Computer object
Usage Example
mycomputer = get_shell.host_computer
print(mycomputer.File("/etc/passwd").content)
// prints the contents of /etc/passwd on the user machine
start_terminal¶
Launches an active terminal. The colour of the terminal will change and show the IP of the connected shell.
Usage Example
shell = get_shell.connect_service("88.137.62.95", 21, "root", "kuroshitsuji", "ftp")
if shell then shell.start_terminal
Intended to be executed on a remote shell
connect_service(IP, port, user, pass, service)¶
Connects to a remote service (i.e. ssh/ftp) to obtain a remote shell. Requires an IP address (string), port (int), username (string), password (string), and takes an optional service (string)
Returns a Shell object or null on failure
Tip
The service parameter defaults to ssh, and need not be defined where connecting to ssh. But when specified, this parameter should be either ftp or ssh.
Usage Example
mypc = get_shell
remote = mypc.connect_service("39.62.143.12", 22, "root", "We<3nigma")
if remote then
print(remote.host_computer.File("/etc/passwd").content)
//prints the contents of /etc/passwd on this remote machine
end if
Info
On failure, the terminal may also output a connection error (e.g. can't connect: incorrect user/password). This comes from the server and passes around the script, direct to the client terminal.
scp(file, folder, shell)¶
Upload or download files to/from the local shell to/from a remote shell
Takes the path (string) to a file on the shell machine, path to a folder (string) on the remote shell machine, and the shell (Shell) of the machine to copy the file to
Returns 1 on success, or a string (containing an error) on failure
Usage Example
myPC = get_shell
remote = myPC.connect_service("31.19.44.137", 22, "root", "AceofSpades")
myPC.scp("/var/system.log", "/root", remote)
// uploads system.log from the user machine to the root directory on the remote machine
remote.scp("/var/system.log", home_dir, myPC)
// downloads system.log from the remote server to the user directory on the user machine
launch(program, params)¶
Executes a program (string path to program) with optional parameters (string)
Returns null on success, or 0 on failure
Usage Example
get_shell.launch("/bin/cat", "/etc/passwd")
Limitations
The launch() function only works with script-based terminal commands.
build(srcpath, buildpath)¶
Compiles an executable binary from a source file
Requires a path to a source file (string) and a directory path (string) to where the binary will be saved. The binary will be created with the same name as the source file, without a file extension.
Returns a string (empty on success, or with an error on failure)
Usage Example
get_shell.build("/home/user/myprogram.src", "/home/user")
Requires absolute paths
You must provide absolute paths (i.e. /full/path/to/file) for both srcpath and buildpath.
masterkey(IP, port, user)¶
Takes an IP (string), port (int), and optional user (string) defaulting to root
Obtains a shell on a machine, regardless of exploits, permissions or closed ports. Returns a shell object, or null on failure
Usage Example
host = get_shell
remote = host.masterkey("83.137.19.41", 80)
// opens a remote shell as root on the specified IP and port
Mods Only
This function is only available to in-game moderators, when moderator tools are enabled. If you are not eligible to use this function, it will return null.
FtpShell¶
FtpShell objects can be instantiated by shell.connect_service when connecting to ftp, and provide the following functions:
start_terminal¶
Alias of shell.start_terminal
put¶
Alias of shell.scp
host_computer¶
Alias of shell.host_computer
masterkey¶
Alias of shell.masterkey
Crypto¶
The Crypto object comes from the Crypto library in /lib/crypto.so and is instantiated by include_lib.
aircrack(filepath)¶
Cracks a router's WiFi password. Requires the path to a pcap file created by the aireplay command
Returns the target router's WiFi password (string) or null on failure (the terminal will also output an error)
aireplay(bssid, essid, maxAcks)¶
Capture packets from a wireless interface. Requires bssid (string) and essid (string), and an optional maxAcks (number).
If maxAcks is not provided, use Ctrl+C to stop the capturing and save data to a file file.cap in the current directory.
If maxAcks is provided, the command will stop automatically once the number of ACKs received exceeds maxAcks, saving the file.cap as described above.
Returns null, or a string containing an error message
airmon(option, interface)¶
Enables/Disables WiFi monitoring. Requires an option (string: either "start" or "stop") and network interface (e.g. "eth0")
Usage Example
crypto = include_lib("/lib/crypto.so")
crypto.airmon("start", "eth0")
decipher(user, encryptedPass)¶
Attempts to decipher an encrypted password.
Takes a username (string) and encrypted password (hash string). Returns either the deciphered password (string), or null on failure
smtp_user_list(IP, port)¶
Connects to a mail service and returns a list object of all users on the machine, along with their email address on the server (or otherwise an email not found string)
Takes an IP address and port (int)
Usage Example
crypto = include_lib("/lib/crypto.so")
mail = crypto.smtp_user_list("88.231.19.24", 25)
print(mail)
["root email not found", "Toche exists [email protected]", "Krireng exists [email protected]"]
MetaLib¶
The MetaLib object represents all libraries in Grey Hack. It can be instantiated by Metaxploit.load.
overflow(memoryAddress, value, extra)¶
Performs a buffer overflow attack on the library at the specified memory address (string) with the specified vulnerable value
Additional data may need to be provided (via the optional extra parameter) for the exploit to work (e.g. if the exploit changes a user's password)
Usage Example
meta = include_lib("/lib/metaxploit.so")
lib = meta.load("/lib/kernel_module.so")
flow = lib.overflow("0x2CF07FF0", "bl_treel")
print("Returned: " + typeof(flow))
guest@Taxelp:/home/guest# myprogram
Starting attack...success!
Privileges obtained from user: Fstevio
Returned: shell
Fstevio@Taxelp/home/Fstevio#
lib_name¶
Returns the file name of the library (string)
version¶
Returns the version number (string) of the library
Usage Example
meta = include_lib("/lib/metaxploit.so")
if not meta then exit("Error: missing /lib/metaxploit.so")
lib = meta.load("/lib/init.so")
if not lib then exit("Error: missing /lib/init.so")
print(lib.version) // 1.0.0
Metaxploit¶
The metaxploit object comes from metaxploit.so which can be found in the hackshop. After downloading it and moving it to the /lib folder, it can be instantiated with include_lib.
load(library)¶
Loads a library (string path) in memory and returns a MetaLib object
Returns either the MetaLib object, or null on failure
net_use(IP, port)¶
Connects to an IP address and establishes a NetSession, which grants remote access to the target's libraries; either the service library running on the optional port (int), or the router libraries if no port has been specified.
Returns a NetSession object, or null on failure
rshell_client(IP, port, procName)¶
Takes an optional port (number) and process name (string).
Launches a process on the victim's machine, which silently tries to continuously connect in the background to the specified address and port.
Setup
For the reverse shell to run successfully, the rshell service must be installed and the portforward configured correctly on the machine where the server is waiting for the victim's connection.
rshell_server¶
Returns a list of shell objects that have been reverse shell connected to this machine.
Setup
In order to manage the connections received, the rshell service must be installed on the machine that receives the victims' connections.
scan(MetaLib)¶
Scans a MetaLib for vulnerable memory addresses and returns them in a list
Returns either the memory addresses (list), or null on failure
scan_address(metalib, memoryAddress)¶
Scans a specific memory address and returns information about all its vulnerabilities
Returns either the information about the memory vulnerabilities (string), or null on failure
sniffer(saveEncSource)¶
Takes an optional argument to save the source (boolean)
The terminal listens to the network packets of any connection that passes through this device.
When any connection information is captured, it prints a string with the obtained data.
It can save the source code of the encode script if saveEncSource is true.
Returns null if the listener could not be started.
NetSession¶
This object is instantiated by Metaxploit.net_use.
dump_lib¶
Returns the MetaLib object of the library behind the service to which the NetSession belongs
Usage Example
meta = include_lib("/lib/metaxploit.so")
net = meta.net_use("88.231.19.24", 22)
libssh = net.dump_lib
print(libssh.lib_name + " v" + libssh.version)
libssh.so v1.0.4