Skip to content

Latest commit

 

History

History
156 lines (110 loc) · 5.95 KB

CONTRIBUTING.md

File metadata and controls

156 lines (110 loc) · 5.95 KB
Raw
layout title description permalink
page
Contributing
Get involved in GTFOBins.
/contributing/

File format

Feel free to use any file in the _gtfobins/ folder as an example.

Each entry is defined in a YAML file placed in the _gtfobins/ folder and named like the executable (binary or script) it refers, without any extension. The file contains a single YAML document enclosed in delimiters: --- and .... The general structure is the following:

---
comment: …
functions:
  <function>:
    - comment: …
      version: …
      code: …
      contexts:
        <context>:
          comment: …
          code: …
          # …
        # …
    # …
  # …
...

Where <function> and <context> are defined in the _data/functions.yml and _data/contexts.yml files respectively.

The optional version field must outline any particular OS or executable requirements that enable the corresponding function.

The contexts object can be omitted altogether, in that case code is assumed to be about the unprivileged context. When a context specifies a specialized code field, it is used in place of the global value, which can be omitted if all the context specifies a specialization. comment instances can always be omitted, while ultimately there must be one code example for each context, either specialized or inherited.

Functions

Some functions support additional fields:

Function Fields
shell blind
command blind
reverse-shell blind tty listener
bind-shell blind tty connector
file-write binary
file-read binary
upload binary receiver
download binary sender
library-load n/a
inherit from

Where:

  • the optional blind field determines whether the example is able to somehow return the output of the execution of commands or not (defaults to false);

  • the optional tty field determines whether the example is able to spawn a full TTY shell or not (defaults to true);

  • the optional binary field determines whether the example is able to handle arbitrary binary data or not (defaults to true);

  • the optional listener field describes how to receive the shell on the other side, it can be either a string (that must match the corresponding key in _data/functions.yml, e.g., TCP), or an object with two optional fields (comment and code);

  • the optional connector field describes how to initiate the shell on the other side, it can be either a string (that must match the corresponding key in _data/functions.yml, e.g., TCP), or an object with two optional fields (comment and code);

  • the optional receiver field describes how to receive data on the other side, it can be either a string (that must match the corresponding key in _data/functions.yml, e.g., TCP), or an object with two optional fields (comment and code);

  • the optional sender field describes how to send data on the other side, it can be either a string (that must match the corresponding key in _data/functions.yml, e.g., TCP), or an object with two optional fields (comment and code);

  • the mandayory from field that is the name of another executable that the example enables.

Contexts

Some contexts support additional fields:

Context Fields
unprivileged n/a
sudo n/a
suid system
capabilities list

Where:

  • the optional system field determines whether the executable uses functions like system that passes commands to the default system shell, which, according to the version used, might or might not drop the privileges (defaults to false);

  • the mandayory list field is the list of Linux capabilities in the format CAP_* that are needed in order to execute this function with bypassed permissions.

Aliases

Additionally, it is possible to add aliases with:

---
alias: <gtfobin>
...

In this case, this entry is an alias of an existing <gtfobin>.

Conventions

Placeholders

Use the following placeholder values where appropriate:

Type Value
Shell executable /bin/sh
Command executable /bin/id
Network port 12345
Data to be written DATA
Whatever value x...x
Input file /path/to/input-file
Output file /path/to/output-file
Attacker host domain attacker.com

Multiline strings

If a multiline string is needed, use the - YAML literal variant to strip trailing newlines, i.e., |-, for example:

some-field: |-
  Some
  multiline
  value

Links

If needed, link to other entries using relative URLs, e.g, [gtfobin](../gtfobin).

Local development

To test local changes, start a local instance with:

make serve

This will spin a Docker container that builds the website, and serves it from http://0.0.0.0:4000. Changes to local files are automatically applied.

Before submitting any pull request, make sure the linter completes successfully:

make lint

Use make clean to clean everything up.