The first and foremost step in exploiting something, a VM, an OS or whatsoever, is by identifying the target, then identify or figure out what is vulnerable in a target machine. There can be multiple vulnerabilities in a system, or in some cases, only one vulnerability. The extent to which the vulnerability can be used to gain previlleges is also one thing to check with.

Consider this Scenario

• A person is running an outdated apache2 server. There are some modules in apache2, which allows RCE (Remote code execution), or even has path traversal / directory traversal endpoints, which allows the user in web to access contents of the filesystem of server in which the webpage is being served through.
• In this case, the attacker can either do a RCE, or just do a directory traversal to disclose invaluable server information. The attacker might choose which one has highest previlleges, based on his/her intent. RCE almost always gives the highest previllege, since it is a code execution.

Clearance 2 : There are several ways to identify vulnerabilities in a target system. An attacker should choose the most efficient and least noisy way to figure out the vulnerability. Below given are some of the ways to identify the vulnerability. Though the way I identified the vulnerability is pretty common.

How did I find it?

Just search the web. Be up to date with the latest security exploits, the 2026 is a year of massive linux exploits, sped up release of exploits and LPEs and CVEs because of the use of AI to figure out bugs in the code and build exploits. Mythos. So, the fact is that - I was already aware of the existence of the exploits and the details of those exploits, what the affect and the extent of damage caused by it. Those are called CVEs.

So, our target machine is Ubuntu 20.04, that is running in my University Labs. But hey wait, I am not exploiting it, I am doing it in my own VM. And this is how it looks like.

Find the kernel version

The uname -r command is used for finding the Linux Kernel Version (Release Version). If the version is smaller than 7.0, then there is a massive probability that the copy fail exploit works in the system. To know if I am using the most up to date Ubuntu version, I need to check the os-release. Unlike the uname -r, there is not specific command, so we have to cat it out from /etc/os-release.

# find the kernel version
uname -r

# find all details about kernel
uname -a

# find the ubuntu version
cat /etc/os-release | grep Ubuntu

Here are the exact outputs as in my victim VM, the screenshots of them, the uname and os-release.

Very clear that the kernel version is very small, 5.15.0-67-generic, whereas the latest is 7.x.x thing. Usage of outdated kernels!!!

But I wanted to cross check the compactability of that exploit in this current victim, so small google search would help us to make sure that we choose the correct exploit. Below given is Google AI verified fact that victim’s kernel is vulnerable.

Now, we need to download the exploit. The best place to go for linux exploits and CVEs is Open Source. And that is how most of the kernel bugs are exposed and fixed in the first place, and those bugs were literally hiding there for most of these years. Next step is to check if git is available in the victim machine. Unfortunately, in my case, it was not available…

• So, open the firefox web browser, go to web, search for cve-2026-31431, which is the standard name for Copy Fail vulnerability. Tons of URLs will show up, use google dorking wisely to filter just github.com URLs. Click some random verifiable PoC, inspect the source code. In my case, I am using C code version of this exploit, which is originally a 732 byte file of python.

• Once that the code is verified, understandable and I know that it causes know threat to Availability, download the ZIP file.

• After the zip file has completed downloading, I need to open the terminal in the Downloads folder, and then unzip the zip using the unzip command - i.e, extract the contents of the zip file. Navigate to the exploits folder, where the C version of the exploit is there. Make sure that you understand the C code.

• After verifying that gcc is there in the victim’s machine (which my lab had, so does the VM), we need to compile the binary. gcc without any -o flag will generate the default binary file named a.out.

gcc exploit.c
# gcc <file.c> 
# a.out file is generated

• Before continuing, we must have a way to verify if the exploit actually worked. We will use the id and whoami to verify the integrity of the current user, or if there is a switch in user, and escalation of previlleges.

# whoami will tell you the current user
whoami
# outputs your username
id
# note that the uid should be 1000.

• Proceed with exploitation, which will provide us with previllege escalation. The below given stuff in terminal is the command I type to get the exploit work.

./a.out
# yeah, that's it, the exploit will work

Now, if we use this escalated permission to tamper the current system state, then it is breach of Integrity at this point. The exploit itself is a direct bypass of Authentication and hence the Authorisation also. After escalation, I ran apt update to update the system. Though this is legit naive harmless prank, the real attackers can cause a real prankless harm by implanting a rootkit to ensure persistence, or whatever they are willing to do.

This exploit uses page cache poisoning, corrupts the page cache during a kernel authentication (cryptographic subsystem), and overwrites into the kernel page cache which is supposed to be read only memory section. This target’s a setuid bit binary such as su or sudo. I will not be going deep into the setuid bits, why they exist and stuffs. For now, this is just an exploitation of a CVE.

It is a cache-only exploit - meaning that this exploit is not permanent. Once the system reboots, the cache in RAM, is deleted, and new cache page is provided, as RAM is volatile memory. But we can just manually tell the kernel to drop the caches by running the following command as sudo.

echo 3 > /proc/sys/vm/drop_caches

But… If the caches are not dropped after the exploit, then the cached binary su will still be loaded, instead of whatever is in original su, which is dis, which is disk. Therefore, just running su will escalate the previllege from user to root.

NOTE : THIS EXPLOIT IS PURELY FOR EDUCATIONAL PURPOSES.

Here is the full main, straight from objdump:

Clearance 2 : To get the similarly same output as below, you have to have objdump installed in your system and run the following command.

objdump -d -M intel ./elf
# provided that you have the elf binary downloaded from the clearance 1.

0000000000001139 <main>:
    1139:  55                      push   rbp
    113a:  48 89 e5                mov    rbp,rsp
    113d:  48 83 ec 10             sub    rsp,0x10
    1141:  48 8d 05 c0 0e 00 00    lea    rax,[rip+0xec0]   # 2008
    1148:  48 89 45 f8             mov    QWORD PTR [rbp-0x8],rax
    114c:  48 8b 45 f8             mov    rax,QWORD PTR [rbp-0x8]
    1150:  48 83 ec 08             sub    rsp,0x8
    1154:  6a 0a                   push   0xa
    1156:  6a 0a                   push   0xa
    1158:  6a 09                   push   0x9
    115a:  6a 0a                   push   0xa
    115c:  6a 09                   push   0x9
    115e:  6a 0a                   push   0xa
    1160:  6a 22                   push   0x22
    1162:  ff 75 f8                push   QWORD PTR [rbp-0x8]
    1165:  6a 22                   push   0x22
    1167:  41 b9 09 00 00 00       mov    r9d,0x9
    116d:  41 b8 0a 00 00 00       mov    r8d,0xa
    1173:  b9 0a 00 00 00          mov    ecx,0xa
    1178:  ba 0a 00 00 00          mov    edx,0xa
    117d:  be 0a 00 00 00          mov    esi,0xa
    1182:  48 89 c7                mov    rdi,rax
    1185:  b8 00 00 00 00          mov    eax,0x0
    118a:  e8 a1 fe ff ff          call   1030 <printf@plt>
    118f:  48 83 c4 50             add    rsp,0x50
    1193:  b8 00 00 00 00          mov    eax,0x0
    1198:  c9                      leave
    1199:  c3                      ret

I have already a lot to unpack. Let’s go piece by piece.

The first three instructions are the standard prologue:

push   rbp          ; save caller's base pointer
mov    rbp, rsp     ; set our own frame base
sub    rsp, 0x10    ; reserve 16 bytes of local space

push is two micro-operations back to back: sub rsp, 8 then mov [rsp], value. The stack grows downward, so pushing something expands it toward lower addresses.

When the linker’s _start calls main, the return address is already sitting on the stack, which means RSP is 8-byte aligned but not 16-byte aligned at that moment. push rbp subtracts another 8 bytes, which brings RSP back to a 16-byte boundary. After that, sub rsp, 0x10 keeps it aligned and carves out 16 bytes of local variable space.

The System V AMD64 ABI requires RSP to be 16-byte aligned before every call instruction. The push rbp at the very top of main is what restores that invariant, since _start already knocked it off by 8 when it called us.

With 16 bytes reserved, we have room for two 8-byte locals. Only one is actually used here: [rbp-0x8].

So, basically the first instruction push copies the caller’s base pointer onto the stack, writing 8 bytes (standard pointer size in x86-64), after making room to accommodate the pointer by micro-operation sub rsp, 8.

Then the next instruction mov copies into the rbp (base pointer) the current rsp’s value (i.e, stack pointer) to setup a new stack frame for the main function.

The final instruction in standard prologue is reserving the space, 16 bytes. (it is 16 and not any other lesser or non multiple as stack address requires to be a multiple of 16)

lea    rax, [rip+0xec0]      ; rax = address of something at 0x2008
mov    QWORD PTR [rbp-0x8], rax   ; store it as a local variable
mov    rax, QWORD PTR [rbp-0x8]   ; load it back into rax

lea does not dereference - it just computes and stores the address. The comment from objdump tells us the resolved address is 0x2008, which lands inside a section the disassembler labelled _IO_stdin_used (a read-only data sentinel the linker drops in). The actual string starts at 0x2008.

The store-then-immediately-load looks redundant and probably is - a compiler generating unoptimised code (-O0) will faithfully write and re-read every local even when it doesn’t have to. The net result: rax holds a pointer to the format string.

This address is computed using RIP-relative addressing: instead of embedding an absolute address (which would break position-independent executables), the instruction says “whatever address I’m currently at, plus 0xec0.” At link time that offset is calculated so the target is always 0x2008 regardless of where the binary gets mapped. rip is a register - Register Instruction Pointer, which points to the next instruction that is to be executed by the CPU.

QWORD PTR : these words are just denoting that the dereferenced address is 8 bytes (quad-word) and is a pointer.

The System V AMD64 ABI lets you pass the first six integer/pointer arguments in registers, in order:

I need to remember these registers in my mind, so as to setup the correct arguments.

rdi, rsi, rdx, rcx, r8, r9

printf here takes 15 arguments (one format string plus fourteen values). Six fit in registers; the remaining nine have to go on the stack. The ABI says stack arguments are pushed right-to-left, so the last argument gets pushed first and ends up deepest in the stack, while argument 7 (the first stack argument) is pushed last and ends up shallowest — right where printf can pick it up.

• How did I figure out the 15 arguments? It is just we need to remember what is moved into the registers.
• The first 6 registers that are meant to take up arguments for a function call took the following values as provided in the below table.
• And there were also push instruction that is copying those values onto the stack, hence growing the stack downwards. Normally, when the registers meant for storing arguments are exhausted, the printf function reads it from the stack, as long as the number of formatters in the format string (first argument) is satisfied.
• But here, the first argument is in the rdi (register destination index) and that is having a pointer to an address, and relative to rip, the address is 2008. But in our objdump output, that address was not shown, because it was in a .rodata section and we need to use the -D flag instead of the -d flag.

Clearance 3 : Therefore, the format string has 14 format specifiers (formatters) and hence, 5 of them stored in registers and the rest of them pushed onto the stack.

Mapping every argument, we just need to write down what is pushed on the stack:

Notice argument 8: push QWORD PTR [rbp-0x8] — this dereferences the local variable and pushes the pointer value itself. So printf receives the address of the format string as one of its own arguments. Mm, interesting takeaway. What string will take itself as its format string?

The sub rsp, 0x8 before the pushes (at 0x1150) is just there to maintain 16-byte alignment as the nine stack arguments are being assembled. After printf returns, add rsp, 0x50 cleans the whole thing up: 0x50 = 80 bytes = 8 (alignment pad) + 9×8 (stack args).

Here, the last argument should be pushed first onto the stack because the stack is first in first out datastructure. Therefore, whatever is pushed at last will be the printf’s next argument.

Notice these push instructions.

1154:  6a 0a                   push   0xa
1156:  6a 0a                   push   0xa
1158:  6a 09                   push   0x9
115a:  6a 0a                   push   0xa
115c:  6a 09                   push   0x9
115e:  6a 0a                   push   0xa
1160:  6a 22                   push   0x22
1162:  ff 75 f8                push   QWORD PTR [rbp-0x8]
1165:  6a 22                   push   0x22

The string lives in the read-only data section starting at 0x2008. objdump -D disassembles everything, including data sections, so it reads those bytes and prints them as if they were x86 instructions — producing nonsense like:

2008:  23 69 6e    and  ebp,DWORD PTR [rcx+0x6e]
200b:  63 6c 75 64 movsxd ebp,DWORD PTR [rbp+rsi*2+0x64]

Those are not real instructions, reverse engineers call them pseudo instructions. They are character bytes being misread as opcodes (assembly instruction keywords). The actual data is just the ASCII values, (which I just copied that entire section starting from 2008 till end of section, put into gemini to provide raw bytes mapped into ascii characters):

The null terminator (00) marks the end. You can verify the whole thing instantly with:

strings elf

The full format string is:

#include <stdio.h>%c#include <stdlib.h>%c%cint main(void) {%c%cconst char* fixed = %c%s%c;%c%cprintf(fixed, 10, 10, 10, 10, 9, 34, fixed, 34, 10, 9, 10, 9, 10, 10);%c%creturn EXIT_SUCCESS;%c}%c

Every %c gets substituted with a character value from the argument list. With '\n' (10) and '\t' (9) in the right slots, the output is properly indented C source. The %s in the middle gets the pointer to fixed itself - argument 8 - so the string prints its own contents as the value of the fixed variable. That is the quine mechanism.

Putting it all together:

int main(void) {

  const char* fixed = "#include <stdio.h>%c#include <stdlib.h>%c%cint main(void) {%c%cconst char* fixed = %c%s%c;%c%cprintf(fixed, 10, 10, 10, 10, 9, 34, fixed, 34, 10, 9, 10, 9, 10, 10);%c%creturn EXIT_SUCCESS;%c}%c";

  printf(fixed, 10, 10, 10, 10, 9, 34, fixed, 34, 10, 9, 10, 9, 10, 10);

  return EXIT_SUCCESS;

}

Run it, and it prints itself. That is the whole program.

The string is both the format template and the data being formatted. %s is the slot where fixed gets inserted back in — verbatim, quotes included (argument 7 is ", argument 8 is the pointer, argument 9 is " again). Everything else is just whitespaces and stuffs I don’t still get yet, weird bytes.

A few things were noticed during this that weren’t obvious previously, like these:

Stack argument ordering is counter-intuitive at first. Arguments beyond the sixth are pushed right-to-left, so argument 15 is on the stack deepest and argument 7 sits on top. Once you know printf reads them left-to-right from where rsp points after the call, the ordering should probably make sense to you as it did to me - it mirrors how a function’s stack frame naturally works.

objdump -d on a data section is actively misleading. The disassembler does not know where code ends and data begins in a stripped binary unless it has section headers to guide it. Treating .rodata bytes as opcodes produces syntactically valid but semantically meaningless output. The right move is to extract the bytes at the known address and decode them as ASCII, or just run strings.

RIP-relative addressing is the default in PIE binaries. lea rax, [rip+0xec0] is not exotic : it is how GCC generates every reference to a global or string literal in a position-independent executable. The offset is baked in at link time and the absolute address resolves at load time.

-O0 output is verbose but readable. The pointless mov [rbp-0x8], rax / mov rax, [rbp-0x8] cycle is a compiler artefact from storing and reloading every value through its stack slot. An optimised build would have eliminated that entirely, making the disassembly shorter but also collapsing the explicit local variable - potentially harder to follow, not easier, but with only a few lines of C code, it would be just a little harder.

And that’s it, this is my first disassembly on a Quine.

• Practical over pure - plain JSON over HTTP/REST, not some exotic new protocol
• Simplicity - minimal moving parts and dependencies
• Full openness - anyone can run a server and join the network (open federation), and the spec itself is public with no patent restrictions
• User control - you pick your own server and client software, you control your own privacy, and you know exactly where your data physically lives. Go to matrix.org, and then try matrix - you would get a list of matrix clients like Element, Element X, Element for web, FluffyChat, and several others.
• No central point of failure or control
• Learning from older protocols - deliberately borrowing good ideas from XMPP, SIP, IRC, SMTP, IMAP, and NNTP while trying to dodge the problems that plagued each of them, and that’s why I think I should use matrix. Moreover, there are no/less API restrictions, so it is easy for me to create matrix bots to send messages, log details, and retrieve them in a private group with only me and my bot.

The spec supports: creating and managing chat rooms with no single owner; keeping room history synced (eventually consistent) across many servers; sending messages with optional end-to-end encryption; a permission system for inviting/kicking/banning members based on power levels; customizable room metadata (name, topic, aliases); user profile data (avatars, display names); account management (register/login/logout); and linking third-party identifiers like email or phone numbers so people can find each other by info they already know, backed by a network of trusted “identity servers” that verify these mappings.

The long-term goal is for Matrix to be a general-purpose sync layer for any structured data between people, devices, or services - not just chat.

• Client-Server API - how your chat app talks to your homeserver: this is what I use for my bot management. You first create a bot account in matrix.org and create a private group for you and your bot. The bot’s homeserver is matrix.org, my primary homeserver may or may not be matrix.org - I may use any other server, thanks again to the Server-Server API, that is matrix.org and anything.org can communicate with each other though they are entirely different servers. After creating and inviting the bot to the group (room), I just use the chat to send a message. Client-Server: the bot is the client, and matrix.org is the server for the bot. In the room, the message needs to reach my primary account - so matrix.org and anything.org will follow the Server-Server API to communicate with each other. Then Server-Client: anything.org will communicate with my primary client to make that message visible.
• Server-Server API - how homeservers talk to each other (this is what “federation” means): server-server is handled by the homeservers themselves, anything that follows the matrix protocol if configured can be added to the federation. So it is just a configuration to write.
• Application Service API - a privileged API for bots/bridges that need to act as many virtual users at once. This is exclusively designed for bots, but right now, I don’t need it - just me and my bot, so there is no need for virtual users.
• Identity Service API - for mapping emails/phone numbers to Matrix accounts
• Push Gateway API - for delivering mobile push notifications
• Plus specs for room versioning and the Olm/Megolm encryption algorithms used for E2EE

Every user has a homeserver - the server that stores their account and message history. When you send a message, here’s the actual path it takes:

1. Your client does an HTTP PUT to your own homeserver with the message content
2. Your homeserver adds this to its local copy of the room’s history, cryptographically signs it
3. Your homeserver forwards it via another HTTP PUT - this time over the Server-Server API - to every other homeserver that has users in that room: that is, if a room has 3 different users with 3 different homeservers, then it would forward it to all three homeservers.
4. Each receiving homeserver checks the signature, validates the content is allowed, and adds it to its own local copy
5. The other users receive the new message via a long-held GET request their client keeps open to their homeserver (this technique is called long-polling)

It is basically all PUT, POST, GET.

So a message you send doesn’t go directly to the recipient - it goes to your homeserver, gets replicated to their homeserver, and their homeserver hands it to them. No message ever needs a single “master” server to pass through.

One important tradeoff: Matrix deliberately prioritizes staying available and tolerating network splits over having perfectly consistent data everywhere instantly (this is a direct reference to the CAP theorem - you can’t fully have Consistency, Availability, and Partition-tolerance all at once, and Matrix picks the latter two).

Every account gets a user ID shaped like an email address: @username:servername. The part after the colon just tells you which homeserver issued the account - it doesn’t mean the conversation data lives only on that server. My bot can be like @mybot:lolcat.org, and primary be like @myname:somekind.com.

In Matrix, “device” doesn’t just mean a physical gadget. Every distinct login session - your phone app, your laptop’s browser tab, a second browser on that same laptop - counts as its own separate “device,” each with its own device_id. This matters primarily for end-to-end encryption: each device gets its own independent set of encryption keys, so you can revoke just one device (e.g., a stolen phone) without logging out everywhere else. Whether a device is long-lived or gets thrown away depends on the app - a website might create a fresh device every time you log in, while a mobile app might keep reusing the same one across sessions.

Device in this context means - everywhere you are logged in, that is each matrix session is a device. To stabilise that session, you would need a device id. That’s it.

Every single action in Matrix - sending a message, changing the room name, someone joining - becomes an event, which is just a JSON object with a type field describing what kind of event it is. Built-in event types defined by the spec always start with m. (like m.room.message); custom application-specific event types must use reverse-domain naming (like com.example.game.score) to avoid clashing with other apps’ custom types.

An important security note baked into the design: event content coming from the network should always be treated as untrusted input. A client or server must validate the shape of an event before trusting any of its fields, since there’s no absolute guarantee every expected field will actually be present or of the right type.

Rather than a simple linear timeline, each room’s history is stored as a directed acyclic graph (DAG) - every event points back to the event(s) that came immediately before it from that server’s perspective. Usually that’s just one prior event, but if two homeservers send messages at almost the same moment, you can get a temporary fork with two parents pointing at the same predecessor, which then merges back together as new events reference both branches.

To keep a sense of chronological order without needing a single global clock, every event carries a depth number - strictly larger than any of its parents’ depth values. This lets any server figure out relative ordering just by walking the graph, even under network delays. The very first event in any room has a depth of 1. This has something to do with graph theory stuffs, but I am not going in depth into this rabbit hole - for now, this is enough to get started with the API.

A room is identified by an opaque ID shaped like !randomstring:servername. That domain suffix is only there to prevent ID collisions globally - it does not mean the room is physically hosted on that one server. In federation, a room’s data is actually replicated across every homeserver that has a member in it (remember - it is replicated).

Room data splits into two categories:

• Message events - one-off, transient activity: a chat message, a call-setup signal, a file share. Say it is just like the messages sent in WhatsApp, like files sent, files received, etc in a group chat.
• State events - durable, current facts about the room: its name, topic, member list, which servers are participating. State works like a key-value table, where each entry’s key is a combination of an event type and a “state key,” and newer state events simply overwrite older ones for that same key. Say it is just like a user viewing the group info.

If two servers create conflicting state changes at nearly the same time (a race condition), Matrix runs a state resolution algorithm to deterministically decide which version wins - every server, regardless of the order it received events in, ends up agreeing on the same outcome.

Each event is cryptographically signed by the server that created it, and that signature covers the event’s parent links, type, depth, and content hash - so tampering is detectable. Servers propagate new events to each other directly (a full-mesh pattern, meaning every server in a room can talk to every other one), and can also request older history (“backfill”) from peers if they’re missing parts of it.

It is better to be read as #roomname rather than !oijup24UIOh, and that is why we have this.

Since room IDs are opaque strings, Matrix also supports aliases shaped like #name:servername - these are the human-readable names you’d actually see or type, like a bookmark. An alias simply points to an underlying room ID, and that mapping isn’t permanent - it can be repointed to a different room ID later. Because of that, clients are expected to resolve an alias to a room ID once and then keep using that ID going forward, rather than re-resolving on every request. Looking up an alias also tells you which servers are known to participate in that room, which is useful info for actually joining it.

A Matrix “identity” combines your Matrix user ID with any external identifiers (email, phone number, etc.) you’ve chosen to link to it. Third-party ID servers - a separate, trusted, federated network of “identity servers” - verify that you actually own that email or phone number and then store the verified mapping, so other users can find your Matrix account by searching for your email instead of needing your exact Matrix ID. This is entirely optional - you can use Matrix without ever touching an identity server, you just lose the ability to be found via 3rd-party contact info.

Users can publish public profile info (display name, avatar image URL, contact details) that others can see, and separately store private key-value data tied to their account (client settings, preferences) using a symmetrical but non-public API.

Namespacing: anything under the m. prefix is officially defined by the spec itself; anything else (custom event types, custom fields) must use reverse-domain naming to avoid two unrelated apps accidentally colliding on the same identifier.

Timestamps: everywhere in the spec, a timestamp means milliseconds since the Unix epoch (Jan 1, 1970 UTC), and leap seconds are deliberately ignored so every day is always treated as exactly 86,400,000 milliseconds - I mean this matches how most programming languages already represent time by default.

Matrix allows you to use simultaneous versions, that is you can use the protocol specifying what version of it you want to use, all with just a single version string in the API path.

The whole specification carries a single version number like vX.Y. A change to X signals something big and breaking (e.g., dropping JSON entirely, changing the cryptographic signing approach). A change to Y means new features added in a backwards-compatible way. There’s no guarantee that, say, v1.3 stays compatible with v1.1 - only that each step (v1.1 → v1.2) is meant to be safe.

Individual endpoints are versioned separately from the spec as a whole - so /v3/sync can be superseded by /v4/sync without touching or breaking /v3/profile, which keeps working exactly as it did.

Deprecation works in stages: a feature first gets marked deprecated (but servers/clients must still support it), then after roughly one spec version of being deprecated, it becomes eligible for full removal in a later version. If your software advertises support for a spec version that included a now-deprecated endpoint, you’re still required to implement it - you only get to drop it once you stop claiming support for that older version.

Legacy versioning: before this unified vX.Y numbering existed, each of the five APIs (Client-Server, Server-Server, Application Service, Identity Service, Push Gateway) was versioned completely independently using an rX.Y.Z scheme. What’s now called “Matrix 1.0” was never an official spec version number - it’s really shorthand for a specific combination of those older per-API version numbers, alongside room versions 1 through 5.

This is an example of bot script that I wrote using python for sending messages to a chat. Potentially it can be used for logging activities and sending files/photos, etc stuff and messages from a host machine to the room. It is based on a json file structure which has the access token to the bot account and room id to the room. This should kinda look like something like this :

{
    "name" : "lolcat-api",
    "bot" : {
        "username" : "some_random_bot",
        "homeserver" : "https://yourhomeserver.tld",
        "access_token" : "rct_euepJKSII0UUJvcvfIsL1L1Brw5Ehb_asds4",
        "device_id" : "0b90dB86UU",
        "user_id" : "@some_random_bot:matrix.org"
    },
    "rooms" : {
        "lolcat-api" : {
            "id" : "!OEpoYrzABCBiEWqe3l:matrix.org",
            "desc" : "A demo for learning matrix API and bot accounts for internet details redirection"
        }
    }
}

Note that the above json code is just the structure of how the json file should look like, nothing is real there.

Next we have this python code which will read and parse the json from the .data.txt file given above, but there is also a variable called CONFIG using which you can change the path of the data.json. For this purpose, we would be using the httpx module, that is more advanced and capable than the requests module in python. Here is the code :

#!/usr/bin/env python3

# import the necessary modules.
import sys
import os
import uuid
import json
import mimetypes
import httpx

# set the global config path.
CONFIG = ".data.json"  # adjust path if needed

# load the config path
def load_config(path=CONFIG):
    with open(path, "r") as f:
        return json.load(f)

# get the home server from the json file.
def get_homeserver(config):
    homeserver = config["bot"]["homeserver"]
    if not homeserver.startswith("http"):
        homeserver = f"https://{homeserver}"
    return homeserver

# define a function to send message to the server.
# for understanding what is happening beneath this function, you need to understand the matrix api.
def send_message(body, room_key, config, html=None):
    homeserver = get_homeserver(config)
    access_token = config["bot"]["access_token"]
    room_id = config["rooms"][room_key]["id"]

    txn_id = uuid.uuid4().hex
    url = f"{homeserver}/_matrix/client/v3/rooms/{room_id}/send/m.room.message/{txn_id}"

    payload = {"msgtype": "m.text", "body": body}
    if html:
        payload["format"] = "org.matrix.custom.html"
        payload["formatted_body"] = html

    resp = httpx.put(
        url,
        json=payload,
        headers={"Authorization": f"Bearer {access_token}"},
    )
    if not resp.is_success:
        sys.exit(f"Matrix API error {resp.status_code}: {resp.text}")

    return resp.json()


def upload_file(filepath, config):
    homeserver = get_homeserver(config)
    access_token = config["bot"]["access_token"]

    mimetype, _ = mimetypes.guess_type(filepath)
    mimetype = mimetype or "application/octet-stream"

    filename = os.path.basename(filepath)
    with open(filepath, "rb") as f:
        data = f.read()

    resp = httpx.post(
        f"{homeserver}/_matrix/media/v3/upload",
        params={"filename": filename},
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": mimetype,
        },
        content=data,
    )
    if not resp.is_success:
        sys.exit(f"Upload failed {resp.status_code}: {resp.text}")

    return resp.json()["content_uri"], mimetype


def send_file(filepath, room_key, config, msgtype="m.file"):
    homeserver = get_homeserver(config)
    access_token = config["bot"]["access_token"]
    room_id = config["rooms"][room_key]["id"]

    mxc_uri, mimetype = upload_file(filepath, config)
    filename = os.path.basename(filepath)
    filesize = os.path.getsize(filepath)

    txn_id = uuid.uuid4().hex
    url = f"{homeserver}/_matrix/client/v3/rooms/{room_id}/send/m.room.message/{txn_id}"

    payload = {
        "msgtype": msgtype,  # m.file, m.image, m.audio, m.video
        "body": filename,
        "url": mxc_uri,
        "info": {"size": filesize, "mimetype": mimetype},
    }

    resp = httpx.put(
        url,
        json=payload,
        headers={"Authorization": f"Bearer {access_token}"},
    )
    if not resp.is_success:
        sys.exit(f"Matrix API error {resp.status_code}: {resp.text}")

    return resp.json()


def main():
    if len(sys.argv) < 4:
        sys.exit(
            "Usage:\n"
            '  python send-files-httpx.py msg <room-key> "message text"\n'
            "  python send-files-httpx.py file <room-key> <filepath> [--type m.image]"
        )

    action, room_key = sys.argv[1], sys.argv[2]
    config = load_config()

    if action == "msg":
        message = sys.argv[3]
        result = send_message(message, room_key, config)
        print(f"Sent message to {room_key}. Event ID: {result.get('event_id')}")

    elif action == "file":
        filepath = sys.argv[3]
        msgtype = "m.file"
        if "--type" in sys.argv:
            msgtype = sys.argv[sys.argv.index("--type") + 1]
        result = send_file(filepath, room_key, config, msgtype=msgtype)
        print(f"Sent file to {room_key}. Event ID: {result.get('event_id')}")

    else:
        sys.exit(f"Unknown action '{action}'. Use 'msg' or 'file'.")


if __name__ == "__main__":
    main()

# usage for this is :
# python3 send-files-httpx.py <msg-type:msg|file> <message|path/to/file> --type <if image, m.image>

How to actually use this script to automate the messaging, sending files and messages?

All we need is just two matrix accounts. (preferable) or even one matrix account (making your primary account act as bot). The difference between the two is that : the room is created by the bot account in first case and the primary account is invited to the room. The latter one, you just create a room and invite no one. You act as a bot and the script sends the message on behalf of you.

Step 1 : Create a primary matrix account in your preferred matrix server. Then procceed creating the bot account in case you don’t want to leak your primary account’s access token.

Step 2 : Figure out your access token. You can do it by just curling to a matrix API endpoint (this entire blog post will give you some kinda help). You can follow this oneliner -

# Run in Terminal/CLI
curl -X POST https://yourserver.tld/_matrix/client/v3/login \
     -H "Content-Type: application/json" \
     -d '{
           "type": "m.login.password",
           "identifier": {"type": "m.id.user", "user": "your_bot_username"},
            "password": "your_bot_passwd"
         }'

Step 3 : Replace the contents of the .data.json file from the results from your curl. You would need to create a room and get its room id. Replace the dummy id in the file with your original room id. Invite your primary account to the room.

Step 4 : Run the python script and you are good to go. See the last comment for usage.

I have not yet published to code to github. I need to document it and explain it, and do some advanced stuffs like defaulting, falling back and learn more of matrix APIs for doing automation and bots. See the official spec given below for more details.