{"id":13605185,"url":"https://github.com/endrazine/wcc","last_synced_at":"2025-05-14T08:09:47.369Z","repository":{"id":10302632,"uuid":"65269564","full_name":"endrazine/wcc","owner":"endrazine","description":"The Witchcraft Compiler Collection","archived":false,"fork":false,"pushed_at":"2025-04-26T17:57:58.000Z","size":8050,"stargazers_count":1877,"open_issues_count":4,"forks_count":109,"subscribers_count":78,"default_branch":"master","last_synced_at":"2025-04-26T18:27:01.278Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/endrazine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-09T06:37:47.000Z","updated_at":"2025-04-26T17:58:01.000Z","dependencies_parsed_at":"2024-05-10T17:32:00.768Z","dependency_job_id":"f248b38c-37c1-40b9-949d-6ef4e1845c64","html_url":"https://github.com/endrazine/wcc","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endrazine%2Fwcc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endrazine%2Fwcc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endrazine%2Fwcc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endrazine%2Fwcc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/endrazine","download_url":"https://codeload.github.com/endrazine/wcc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101559,"owners_count":22014908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:00:55.497Z","updated_at":"2025-05-14T08:09:42.361Z","avatar_url":"https://github.com/endrazine.png","language":"C","readme":"\n\n#     The Witchcraft Compiler Collection\n\nWelcome to the Witchcraft Compiler Collection !\n\n## Purpose\nWCC is a collection of compilation tools to perform binary black magic on the GNU/Linux and other POSIX platforms.\n\n## User manual\n\nThe WCC user manual is available online at : https://github.com/endrazine/wcc/wiki\n\n## Installation\n\n### Installation Requirements\nThe Witchcraft Compiler Collection requires the following software to be installed:\n\n    capstone, glibc, libbfd, libdl, zlib, libelf, libreadline, libgsl, make\n\n### Installation Requirements on Ubuntu/Debian\nUnder Ubuntu/Debian those dependencies can be installed with the following commands (tested on Ubuntu 22.04):\n    \n    sudo apt-get install -y clang libbfd-dev uthash-dev libelf-dev libcapstone-dev  libreadline-dev libiberty-dev libgsl-dev build-essential git debootstrap file\n\n## Building and Installing:\n\n### Fetching the code over git\nThis will download the code of wcc from the internet to a directory named wcc in the current working directory:\n\n    git clone https://github.com/endrazine/wcc.git\n\nYou can then enter this directory with:\n\n    cd wcc\n\n### Initializing git submodules\nFrom your root wcc directory, type:\n\n    git submodule init\n    git submodule update\n\n#### Building WCC\nFrom your root wcc directory, type:\n\n    make\n#### Installing WCC\nThen to install wcc, type:\n\n    sudo make install\n\n#### Building the WCC documentation (Optional)\nWCC makes use of doxygen to generate its documentation. From the root wcc directory, type\n\n    make documentation\n\n\n## Core commands\nThe following commands constitute the core of the Witchcraft Compiler Collection.\n\n### wld : The Witchcraft Linker.\nwld takes an ELF executable as an input and modifies it to create a shared library.\n#### wld command line options\n\tjonathan@blackbox:~$ wld\n\tWitchcraft Compiler Collection (WCC) version:0.0.6    (18:10:51 May 10 2024)\n\n\tUsage: wld -libify [-noinit] file\n\n\tOptions:\n\t    -libify          Transform executable into shared library.\n\t    -noinit          Ignore constructors and desctructors in output library.\n\tjonathan@blackbox:~$ \n#### Example usage of wld\nThe following example libifies the executable /bin/ls into a shared library named /tmp/ls.so.\n\n\tjonathan@blackbox:~$ cp /bin/ls /tmp/ls.so\n\tjonathan@blackbox:~$ wld -libify /tmp/ls.so\n\tjonathan@blackbox:~$ \n\n#### Limits of wld\nwld currently only works on ELF binaries. However wld can process ELF executables irrelevant of their architecture or operating system. wld could for instance process Intel, ARM or SPARC executables from Android, Linux, BSD or UNIX operating systems and transform them into \"non relocatable shared libraries\". Feel free to refer to the documentation under the /doc directory for more ample details.\n\n### wcc : The Witchcraft Compiler.\nThe wcc compiler takes binaries (ELF, PE, ...) as an input and creates valid ELF binaries as an output. It can be used to create relocatable object files from executables or shared libraries. \n\n#### wcc command line options\n\tjonathan@blackbox:~$ wcc\n\tWitchcraft Compiler Collection (WCC) version:0.0.6    (18:10:50 May 10 2024)\n\n\tUsage: wcc [options] file\n\n\toptions:\n\n\t    -o, --output           \u003coutput file\u003e\n\t    -m, --march            \u003carchitecture\u003e\n\t    -e, --entrypoint       \u003c0xaddress\u003e\n\t    -i, --interpreter      \u003cinterpreter\u003e\n\t    -p, --poison           \u003cpoison\u003e\n\t    -s, --shared\n\t    -c, --compile\n\t    -S, --static\n\t    -x, --strip\n\t    -X, --sstrip\n\t    -E, --exec\n\t    -C, --core\n\t    -O, --original\n\t    -D, --disasm\n\t    -d, --debug\n\t    -h, --help\n\t    -v, --verbose\n\t    -V, --version\n\n\n\tjonathan@blackbox:~$ \n\n#### Example usage of wcc\nThe primary use of wcc is to \"unlink\" (undo the work of a linker) ELF binaries, either executables or shared libraries, back into relocatable shared objects.\nThe following command line attempts to unlink the binary /bin/ls (from GNU binutils) into a relocatable file named /tmp/ls.o\n\n    jonathan@blackbox:~$ wcc -c /bin/ls -o /tmp/ls.o\n    jonathan@blackbox:~$ \n\nThis relocatable file can then be used as if it had been directly produced by a compiler. The following command would use the gcc compiler to link /tmp/ls.o into a shared library /tmp/ls.so\n\n\tjonathan@blackbox:~$ gcc /tmp/ls.o -o /tmp/ls.so -shared\n\tjonathan@blackbox:~$ \n\n#### Limits of wcc\nwcc will process any file supported by libbfd and produce ELF files that will contain the same mapping when relinked and executed. This includes PE or OSX COFF files in 32 or 64 bits. However, rebuilding relocations is currently supported only for Intel ELF x86_64 binaries. Transforming a PE into an ELF and invoking pure functions is for instance supported.\n\n### wsh : The Witchcraft shell\nThe witchcraft shell accepts ELF shared libraries, ELF ET_DYN executables and Witchcraft Shell Scripts written in Punk-C as an input. It loads all the executables in its own address space and makes their API available for programming in its embedded interpreter. This provides for binaries functionalities similar to those provided via reflection on languages like Java.\n\n#### wsh command line options\n\n\tjonathan@blackbox:~$ wsh -h\n\tUsage: wsh [script] [-h|-q|-v|-V|-g] [binary1] [binary2] ... [-x [script_arg1] [script_arg2] ...]\n\n\tOptions:\n\n\t    -x, --args                Optional script argument separator\n\t    -q, --quiet               Display less output\n\t    -v, --verbose             Display more output\n\t    -g, --global              Bind symbols globally\n\t    -V, --version             Display version and build, then exit\n\n\tScript:\n\n\t    If the first argument is an existing file which is not a known binary file format,\n\t    it is assumed to be a lua script and gets executed.\n\n\tBinaries:\n\n\t    Any binary file name before the -x tag gets loaded before running the script.\n\t    The last binary loaded is the main binary analyzed.\n\n\tjonathan@blackbox:~$ \n\n\n#### Example usage of wsh\nThe following command loads the /usr/sbin/apache2 executable within wsh, calls the ap_get_server_banner() function within\napache to retrieve its banner and displays it within the wsh interpreter.\n\n\tjonathan@blackbox:~$ wsh /usr/sbin/apache2\n\t\u003e a = ap_get_server_banner()\n\t\u003e print(a)\n\tApache/2.4.7\n\t\u003e \n\t\nTo get help at any time from the wsh interpreter, simply type help. To get help on a particular topic, type help(\"topic\").\n\nThe following example illustrates how to display the main wsh help from the interpreter and how to get detailed help on the grep command by calling help(\"grep\") from the wsh interpreter.\n\n\t\u003e help\n\t  [Shell commands]\n\n\t\thelp, quit, exit, shell, exec, clear\n\n\t  [Functions]\n\n\t + basic:\n\t\thelp(), man()\n\n\t + memory display:\n\t\t hexdump(), hex_dump(), hex()\n\n\t + memory maps:\n\t\tshdrs(), phdrs(), map(), procmap(), bfmap()\n\n\t + symbols:\n\t\tsymbols(), functions(), objects(), info(), search(), headers()\n\n\t + memory search:\n\t\tgrep(), grepptr()\n\n\t + load libaries:\n\t\tloadbin(), libs(), entrypoints(), rescan()\n\n\t + code execution:\n\t\tlibcall()\n\n\t + buffer manipulation:\n\t\txalloc(), ralloc(), xfree(), balloc(), bset(), bget(), rdstr(), rdnum()\n\n\t + control flow:\n\t\t breakpoint(), bp()\n\n\t + system settings:\n\t\tenableaslr(), disableaslr()\n\n\t + settings:\n\t\t verbose(), hollywood()\n\n\t + advanced:\n\t\tltrace()\n\n\tTry help(\"cmdname\") for detailed usage on command cmdname.\n\n\t\u003e help(\"grep\")\n\n\t\tWSH HELP FOR FUNCTION grep\n\n\n\tNAME\n\n\t\tgrep\n\n\tSYNOPSIS\n\n\t\ttable match = grep(\u003cpattern\u003e, [patternlen], [dumplen], [before])\n\n\tDESCRIPTION\n\n\t\tSearch \u003cpattern\u003e in all ELF sections in memory. Match [patternlen] bytes, then display [dumplen] bytes, optionally including [before] bytes before the match. Results are displayed in enhanced decimal form\n\n\tRETURN VALUES\n\n\t\tReturns 1 lua table containing matching memory addresses.\n\n\n\t\u003e \n\n#### Extending wsh with Witchcraft Shell Scripts\nThe combination of a full lua interpreter in the same address space as the loaded executables and shared libraries in combination with the reflection like capabilities of wsh allow calling any function loaded in the address space from the wsh interpreter transparently. The resulting API, a powerful combination of lua and C API is called Punk-C. Wsh is fully scriptable in Punk-C, and executes Punk-C on the fly via its dynamic interpreter.\nScripts in Punk C can be invoked by specifying the full path to wsh in the magic bytes of a wsh shell. \nThe following command displays the content of a Witchcraft shell script:\n\n\tjonathan@blackbox:/usr/share/wcc/scripts$ cat md5.wsh\n\t#!/usr/bin/wsh\n\n\t-- Computing a MD5 sum using cryptographic functions from foreign binaries (eg: sshd/OpenSSL)\n\n\tfunction str2md5(input)\n\n\t\tout = calloc(33, 1)\n\t\tctx = calloc(1024, 1)\n\n\t\tMD5_Init(ctx)\n\t\tMD5_Update(ctx, input, strlen(input))\n\t\tMD5_Final(out, ctx)\n\n\t\tfree(ctx)\n\t\treturn out\n\tend\n\n\tinput = \"Message needing hashing\\n\"\n\thash = str2md5(input)\n\thexdump(hash,16)\n\n\texit(0)\n\tjonathan@blackbox:/usr/share/wcc/scripts$ \n\n\nTo run this script using the API made available inside the address space of sshd, simply run:\n\n\tjonathan@blackbox:/usr/share/wcc/scripts$ ./md5.wsh /usr/sbin/sshd \n\t0x43e8b280    d6 fc 46 91 b0 6f ab 75 4d 9c a7 58 6d 9c 7e 36    V|F.0o+uM.'Xm.~6\n\tjonathan@blackbox:/usr/share/wcc/scripts$ \n\n\n\n#### Limits of wsh\nwsh can only load shared libraries and ET_DYN dynamically linked ELF executables directly. This means ET_EXEC executables may need to be libified using wld before use in wsh. Binaries in other file formats might need to be turned into ELF files using wcc.\n\n#### Note: Analysing and Executing ARM/SPARC/MIPS binaries \"natively\" on Intel x86_64 cpus via JIT binary translation\nwsh can be cross compiled to ARM, SPARC, MIPS and other platforms and used in association with the qemu's user space emulation mode to provide JIT binary translation on the fly and analyse shared libraries and binaries from other cpus without requiring emulation of a full operating system in a virtual machine. The analyzed binaries are translated from one CPU to an other, and the analysed binaries, the wsh cross compiled analyser and the qemu binary translator share the address space of a single program. This significantly diminishes the complexity of analysing binaries across different hardware by seemingly allowing to run ARM or SPARC binaries on a linux x86_64 machine natively and transparently.\n\n## Other commands\n\nThe following auxiliary commands are available with WCC. They are typically simple scripts built on top of WCC.\n\n### wldd : print shared libraries compilation flags\nWhen compiling C code, it is often required to pass extra arguments to the compiler to signify which shared libraries should be explicitly linked against the compile code. Figuring out those compilation parameters can be cumbersome. The wldd commands displays the shared libraries compilation flags given at compile time for any given ELF binary.\n\n#### wldd command line options\n\n\tjonathan@blackbox:~$ wldd \n\tUsage: /usr/bin/wldd \u003c/path/to/bin\u003e\n\n\t  Returns libraries to be passed to gcc to relink this application.\n\n\tjonathan@blackbox:~$ \n\n#### Example usage of wldd\nThe following command displays shared libraries compilation flags as passed to gcc when compiling /bin/ls from GNU binutils:\n\n\tjonathan@blackbox:~$ wldd /bin/ls\n\t-lselinux -lacl -lc -lpcre -ldl -lattr \n\tjonathan@blackbox:~$\n\n### wcch : generate C headers from binaries\nThe wcch command takes an ELF binary path as a command line, and outputs a minimal C header file declaring all the exported global variables and functions from the input binary. This automates prototypes declaration when writing C code and linking with a binary for which C header files are not available.\n\n#### Example usage of wcch\n\nThe following command instructs wcch to generate C headers from the apache2 executable and redirects the output from the standard output to a file named /tmp/apache2.h ready for use as a header in a C application.\n\n\tjonathan@blackbox:~$ wcch /usr/sbin/apache2 \u003e/tmp/apache2.h\n\tjonathan@blackbox:~$ \n\n## Downloading the source code\nThe official codebase of the Witchcraft Compiler Collection is hosted on github at https://github.com/endrazine/wcc/ . It uses git modules, so some extra steps are needed to fetch all the code including dependencies. To download the source code of wcc, in a terminal, type:\n\n    git clone https://github.com/endrazine/wcc.git\n    cd wcc\n    git submodule init\n    git submodule update\n\nThis will create a directory named wcc and fetch all required source code in it.\n\n## Greetings\nThe Witchcraft Compiler Collection uses the following amazing Open Source third party software:\n\n  - Capstone, a lightweight multi-platform, multi-architecture disassembly framework http://www.capstone-engine.org/\n  - Linenoise, A small self-contained alternative to readline and libedit https://github.com/antirez/linenoise\n  - Openlibm, High quality system independent, portable, open source libm implementation https://github.com/JuliaMath/openlibm\n  - Lua, The Programming Language Lua https://www.lua.org/\n  - LuaJit, a Just-In-Time Compiler for Lua http://luajit.org/\n  - Qemu, in particular its user space mode : https://qemu-project.gitlab.io/qemu/user/main.html\n  - Uthash and Utlist, Hash tables and linked list implemented as C headers https://troydhanson.github.io/uthash/\n\n## Testing\n\nThe following companion repository exsists to help test WCC: https://github.com/endrazine/wcc-tests\n\n## Licence\nThe Witchcraft Compiler Collection is published under the MIT License.\nPlease refer to the file named [LICENSE](LICENSE) for more information.\n\n","funding_links":[],"categories":["C","Verticals","Mobile"],"sub_categories":["Educational and Toy Projects","Linux/ *Nix"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendrazine%2Fwcc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fendrazine%2Fwcc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendrazine%2Fwcc/lists"}