Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(rube): M1 Marshal stream parser - inspect payloads without deserializing
CarterPerez-devf5196252e967
diff --git a/PROJECTS/beginner/deserialization-gadget-lab/.gitignore b/PROJECTS/beginner/deserialization-gadget-lab/.gitignorenew file mode 100644index 00000000..2dbe4cb8--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/.gitignore@@ -0,0 +1,26 @@+# ©AngelaMos | 2026+# .gitignore++# Dev-only docs (research / plans / context / handoffs) never ship to the public repo+docs/++# Agent briefing, local only+AGENTS.md++# Ruby build + dependency artifacts+*.gem+/pkg/+/tmp/+/.bundle/+/vendor/bundle/+Gemfile.lock+.rspec_status++# Lab working data+/payloads/+/loot/+*.marshal+*.bin++# Local env+.envdiff --git a/PROJECTS/beginner/deserialization-gadget-lab/.rubocop.yml b/PROJECTS/beginner/deserialization-gadget-lab/.rubocop.ymlnew file mode 100644index 00000000..232b5dfc--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/.rubocop.yml@@ -0,0 +1,39 @@+# ©AngelaMos | 2026+# .rubocop.yml++plugins:+ - rubocop-minitest+ - rubocop-performance+ - rubocop-rake++AllCops:+ NewCops: enable+ TargetRubyVersion: 3.3+ Exclude:+ - "vendor/**/*"+ - "target/**/*"+ - "docs/**/*"++Style/Documentation:+ Enabled: false++Style/FrozenStringLiteralComment:+ Enabled: false++Metrics/MethodLength:+ Max: 30++Metrics/AbcSize:+ Max: 30++Metrics/CyclomaticComplexity:+ Max: 30++Metrics/PerceivedComplexity:+ Max: 30++Metrics/ClassLength:+ Max: 250++Layout/LineLength:+ Max: 120diff --git a/PROJECTS/beginner/deserialization-gadget-lab/CHANGELOG.md b/PROJECTS/beginner/deserialization-gadget-lab/CHANGELOG.mdnew file mode 100644index 00000000..d59ef371--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/CHANGELOG.md@@ -0,0 +1,19 @@+# Changelog++All notable changes to rube are documented here.++The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).++## [Unreleased]++### Added++- Marshal stream parser that extracts structure, class names, and gadget sinks+ from a serialized payload without ever calling `Marshal.load`+- Sink classification along the gated/ungated dispatch axis: `marshal_load` and+ `_load` are reached through a `respond_to?` check, while `hash`, `eql?`, `<=>`+ and `[]=` are dispatched blind+- Stream validation rejecting truncated payloads, unsupported version bytes,+ unknown type tags, out-of-bounds object links and symlinks, oversized fixnum+ widths, trailing bytes, and nesting beyond a configurable depth limitdiff --git a/PROJECTS/beginner/deserialization-gadget-lab/Gemfile b/PROJECTS/beginner/deserialization-gadget-lab/Gemfilenew file mode 100644index 00000000..da97d140--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/Gemfile@@ -0,0 +1,13 @@+# ©AngelaMos | 2026+# Gemfile++source "https://rubygems.org"++gemspec++gem "minitest", "~> 6.0"+gem "rake", "~> 13.3"+gem "rubocop", "~> 1.88"+gem "rubocop-minitest", "~> 0.38"+gem "rubocop-performance", "~> 1.26"+gem "rubocop-rake", "~> 0.7"diff --git a/PROJECTS/beginner/deserialization-gadget-lab/LICENSE b/PROJECTS/beginner/deserialization-gadget-lab/LICENSEnew file mode 100644index 00000000..0ad25db4--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/LICENSE@@ -0,0 +1,661 @@+ GNU AFFERO GENERAL PUBLIC LICENSE+ Version 3, 19 November 2007++ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>+ Everyone is permitted to copy and distribute verbatim copies+ of this license document, but changing it is not allowed.++ Preamble++ The GNU Affero General Public License is a free, copyleft license for+software and other kinds of works, specifically designed to ensure+cooperation with the community in the case of network server software.++ The licenses for most software and other practical works are designed+to take away your freedom to share and change the works. By contrast,+our General Public Licenses are intended to guarantee your freedom to+share and change all versions of a program--to make sure it remains free+software for all its users.++ When we speak of free software, we are referring to freedom, not+price. Our General Public Licenses are designed to make sure that you+have the freedom to distribute copies of free software (and charge for+them if you wish), that you receive source code or can get it if you+want it, that you can change the software or use pieces of it in new+free programs, and that you know you can do these things.++ Developers that use our General Public Licenses protect your rights+with two steps: (1) assert copyright on the software, and (2) offer+you this License which gives you legal permission to copy, distribute+and/or modify the software.++ A secondary benefit of defending all users' freedom is that+improvements made in alternate versions of the program, if they+receive widespread use, become available for other developers to+incorporate. Many developers of free software are heartened and+encouraged by the resulting cooperation. However, in the case of+software used on network servers, this result may fail to come about.+The GNU General Public License permits making a modified version and+letting the public access it on a server without ever releasing its+source code to the public.++ The GNU Affero General Public License is designed specifically to+ensure that, in such cases, the modified source code becomes available+to the community. It requires the operator of a network server to+provide the source code of the modified version running there to the+users of that server. Therefore, public use of a modified version, on+a publicly accessible server, gives the public access to the source+code of the modified version.++ An older license, called the Affero General Public License and+published by Affero, was designed to accomplish similar goals. This is+a different license, not a version of the Affero GPL, but Affero has+released a new version of the Affero GPL which permits relicensing under+this license.++ The precise terms and conditions for copying, distribution and+modification follow.++ TERMS AND CONDITIONS++ 0. Definitions.++ "This License" refers to version 3 of the GNU Affero General Public License.++ "Copyright" also means copyright-like laws that apply to other kinds of+works, such as semiconductor masks.++ "The Program" refers to any copyrightable work licensed under this+License. Each licensee is addressed as "you". "Licensees" and+"recipients" may be individuals or organizations.++ To "modify" a work means to copy from or adapt all or part of the work+in a fashion requiring copyright permission, other than the making of an+exact copy. The resulting work is called a "modified version" of the+earlier work or a work "based on" the earlier work.++ A "covered work" means either the unmodified Program or a work based+on the Program.++ To "propagate" a work means to do anything with it that, without+permission, would make you directly or secondarily liable for+infringement under applicable copyright law, except executing it on a+computer or modifying a private copy. Propagation includes copying,+distribution (with or without modification), making available to the+public, and in some countries other activities as well.++ To "convey" a work means any kind of propagation that enables other+parties to make or receive copies. Mere interaction with a user through+a computer network, with no transfer of a copy, is not conveying.++ An interactive user interface displays "Appropriate Legal Notices"+to the extent that it includes a convenient and prominently visible+feature that (1) displays an appropriate copyright notice, and (2)+tells the user that there is no warranty for the work (except to the+extent that warranties are provided), that licensees may convey the+work under this License, and how to view a copy of this License. If+the interface presents a list of user commands or options, such as a+menu, a prominent item in the list meets this criterion.++ 1. Source Code.++ The "source code" for a work means the preferred form of the work+for making modifications to it. "Object code" means any non-source+form of a work.++ A "Standard Interface" means an interface that either is an official+standard defined by a recognized standards body, or, in the case of+interfaces specified for a particular programming language, one that+is widely used among developers working in that language.++ The "System Libraries" of an executable work include anything, other+than the work as a whole, that (a) is included in the normal form of+packaging a Major Component, but which is not part of that Major+Component, and (b) serves only to enable use of the work with that+Major Component, or to implement a Standard Interface for which an+implementation is available to the public in source code form. A+"Major Component", in this context, means a major essential component+(kernel, window system, and so on) of the specific operating system+(if any) on which the executable work runs, or a compiler used to+produce the work, or an object code interpreter used to run it.++ The "Corresponding Source" for a work in object code form means all+the source code needed to generate, install, and (for an executable+work) run the object code and to modify the work, including scripts to+control those activities. However, it does not include the work's+System Libraries, or general-purpose tools or generally available free+programs which are used unmodified in performing those activities but+which are not part of the work. For example, Corresponding Source+includes interface definition files associated with source files for+the work, and the source code for shared libraries and dynamically+linked subprograms that the work is specifically designed to require,+such as by intimate data communication or control flow between those+subprograms and other parts of the work.++ The Corresponding Source need not include anything that users+can regenerate automatically from other parts of the Corresponding+Source.++ The Corresponding Source for a work in source code form is that+same work.++ 2. Basic Permissions.++ All rights granted under this License are granted for the term of+copyright on the Program, and are irrevocable provided the stated+conditions are met. This License explicitly affirms your unlimited+permission to run the unmodified Program. The output from running a+covered work is covered by this License only if the output, given its+content, constitutes a covered work. This License acknowledges your+rights of fair use or other equivalent, as provided by copyright law.++ You may make, run and propagate covered works that you do not+convey, without conditions so long as your license otherwise remains+in force. You may convey covered works to others for the sole purpose+of having them make modifications exclusively for you, or provide you+with facilities for running those works, provided that you comply with+the terms of this License in conveying all material for which you do+not control copyright. Those thus making or running the covered works+for you must do so exclusively on your behalf, under your direction+and control, on terms that prohibit them from making any copies of+your copyrighted material outside their relationship with you.++ Conveying under any other circumstances is permitted solely under+the conditions stated below. Sublicensing is not allowed; section 10+makes it unnecessary.++ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.++ No covered work shall be deemed part of an effective technological+measure under any applicable law fulfilling obligations under article+11 of the WIPO copyright treaty adopted on 20 December 1996, or+similar laws prohibiting or restricting circumvention of such+measures.++ When you convey a covered work, you waive any legal power to forbid+circumvention of technological measures to the extent such circumvention+is effected by exercising rights under this License with respect to+the covered work, and you disclaim any intention to limit operation or+modification of the work as a means of enforcing, against the work's+users, your or third parties' legal rights to forbid circumvention of+technological measures.++ 4. Conveying Verbatim Copies.++ You may convey verbatim copies of the Program's source code as you+receive it, in any medium, provided that you conspicuously and+appropriately publish on each copy an appropriate copyright notice;+keep intact all notices stating that this License and any+non-permissive terms added in accord with section 7 apply to the code;+keep intact all notices of the absence of any warranty; and give all+recipients a copy of this License along with the Program.++ You may charge any price or no price for each copy that you convey,+and you may offer support or warranty protection for a fee.++ 5. Conveying Modified Source Versions.++ You may convey a work based on the Program, or the modifications to+produce it from the Program, in the form of source code under the+terms of section 4, provided that you also meet all of these conditions:++ a) The work must carry prominent notices stating that you modified+ it, and giving a relevant date.++ b) The work must carry prominent notices stating that it is+ released under this License and any conditions added under section+ 7. This requirement modifies the requirement in section 4 to+ "keep intact all notices".++ c) You must license the entire work, as a whole, under this+ License to anyone who comes into possession of a copy. This+ License will therefore apply, along with any applicable section 7+ additional terms, to the whole of the work, and all its parts,+ regardless of how they are packaged. This License gives no+ permission to license the work in any other way, but it does not+ invalidate such permission if you have separately received it.++ d) If the work has interactive user interfaces, each must display+ Appropriate Legal Notices; however, if the Program has interactive+ interfaces that do not display Appropriate Legal Notices, your+ work need not make them do so.++ A compilation of a covered work with other separate and independent+works, which are not by their nature extensions of the covered work,+and which are not combined with it such as to form a larger program,+in or on a volume of a storage or distribution medium, is called an+"aggregate" if the compilation and its resulting copyright are not+used to limit the access or legal rights of the compilation's users+beyond what the individual works permit. Inclusion of a covered work+in an aggregate does not cause this License to apply to the other+parts of the aggregate.++ 6. Conveying Non-Source Forms.++ You may convey a covered work in object code form under the terms+of sections 4 and 5, provided that you also convey the+machine-readable Corresponding Source under the terms of this License,+in one of these ways:++ a) Convey the object code in, or embodied in, a physical product+ (including a physical distribution medium), accompanied by the+ Corresponding Source fixed on a durable physical medium+ customarily used for software interchange.++ b) Convey the object code in, or embodied in, a physical product+ (including a physical distribution medium), accompanied by a+ written offer, valid for at least three years and valid for as+ long as you offer spare parts or customer support for that product+ model, to give anyone who possesses the object code either (1) a+ copy of the Corresponding Source for all the software in the+ product that is covered by this License, on a durable physical+ medium customarily used for software interchange, for a price no+ more than your reasonable cost of physically performing this+ conveying of source, or (2) access to copy the+ Corresponding Source from a network server at no charge.++ c) Convey individual copies of the object code with a copy of the+ written offer to provide the Corresponding Source. This+ alternative is allowed only occasionally and noncommercially, and+ only if you received the object code with such an offer, in accord+ with subsection 6b.++ d) Convey the object code by offering access from a designated+ place (gratis or for a charge), and offer equivalent access to the+ Corresponding Source in the same way through the same place at no+ further charge. You need not require recipients to copy the+ Corresponding Source along with the object code. If the place to+ copy the object code is a network server, the Corresponding Source+ may be on a different server (operated by you or a third party)+ that supports equivalent copying facilities, provided you maintain+ clear directions next to the object code saying where to find the+ Corresponding Source. Regardless of what server hosts the+ Corresponding Source, you remain obligated to ensure that it is+ available for as long as needed to satisfy these requirements.++ e) Convey the object code using peer-to-peer transmission, provided+ you inform other peers where the object code and Corresponding+ Source of the work are being offered to the general public at no+ charge under subsection 6d.++ A separable portion of the object code, whose source code is excluded+from the Corresponding Source as a System Library, need not be+included in conveying the object code work.++ A "User Product" is either (1) a "consumer product", which means any+tangible personal property which is normally used for personal, family,+or household purposes, or (2) anything designed or sold for incorporation+into a dwelling. In determining whether a product is a consumer product,+doubtful cases shall be resolved in favor of coverage. For a particular+product received by a particular user, "normally used" refers to a+typical or common use of that class of product, regardless of the status+of the particular user or of the way in which the particular user+actually uses, or expects or is expected to use, the product. A product+is a consumer product regardless of whether the product has substantial+commercial, industrial or non-consumer uses, unless such uses represent+the only significant mode of use of the product.++ "Installation Information" for a User Product means any methods,+procedures, authorization keys, or other information required to install+and execute modified versions of a covered work in that User Product from+a modified version of its Corresponding Source. The information must+suffice to ensure that the continued functioning of the modified object+code is in no case prevented or interfered with solely because+modification has been made.++ If you convey an object code work under this section in, or with, or+specifically for use in, a User Product, and the conveying occurs as+part of a transaction in which the right of possession and use of the+User Product is transferred to the recipient in perpetuity or for a+fixed term (regardless of how the transaction is characterized), the+Corresponding Source conveyed under this section must be accompanied+by the Installation Information. But this requirement does not apply+if neither you nor any third party retains the ability to install+modified object code on the User Product (for example, the work has+been installed in ROM).++ The requirement to provide Installation Information does not include a+requirement to continue to provide support service, warranty, or updates+for a work that has been modified or installed by the recipient, or for+the User Product in which it has been modified or installed. Access to a+network may be denied when the modification itself materially and+adversely affects the operation of the network or violates the rules and+protocols for communication across the network.++ Corresponding Source conveyed, and Installation Information provided,+in accord with this section must be in a format that is publicly+documented (and with an implementation available to the public in+source code form), and must require no special password or key for+unpacking, reading or copying.++ 7. Additional Terms.++ "Additional permissions" are terms that supplement the terms of this+License by making exceptions from one or more of its conditions.+Additional permissions that are applicable to the entire Program shall+be treated as though they were included in this License, to the extent+that they are valid under applicable law. If additional permissions+apply only to part of the Program, that part may be used separately+under those permissions, but the entire Program remains governed by+this License without regard to the additional permissions.++ When you convey a copy of a covered work, you may at your option+remove any additional permissions from that copy, or from any part of+it. (Additional permissions may be written to require their own+removal in certain cases when you modify the work.) You may place+additional permissions on material, added by you to a covered work,+for which you have or can give appropriate copyright permission.++ Notwithstanding any other provision of this License, for material you+add to a covered work, you may (if authorized by the copyright holders of+that material) supplement the terms of this License with terms:++ a) Disclaiming warranty or limiting liability differently from the+ terms of sections 15 and 16 of this License; or++ b) Requiring preservation of specified reasonable legal notices or+ author attributions in that material or in the Appropriate Legal+ Notices displayed by works containing it; or++ c) Prohibiting misrepresentation of the origin of that material, or+ requiring that modified versions of such material be marked in+ reasonable ways as different from the original version; or++ d) Limiting the use for publicity purposes of names of licensors or+ authors of the material; or++ e) Declining to grant rights under trademark law for use of some+ trade names, trademarks, or service marks; or++ f) Requiring indemnification of licensors and authors of that+ material by anyone who conveys the material (or modified versions of+ it) with contractual assumptions of liability to the recipient, for+ any liability that these contractual assumptions directly impose on+ those licensors and authors.++ All other non-permissive additional terms are considered "further+restrictions" within the meaning of section 10. If the Program as you+received it, or any part of it, contains a notice stating that it is+governed by this License along with a term that is a further+restriction, you may remove that term. If a license document contains+a further restriction but permits relicensing or conveying under this+License, you may add to a covered work material governed by the terms+of that license document, provided that the further restriction does+not survive such relicensing or conveying.++ If you add terms to a covered work in accord with this section, you+must place, in the relevant source files, a statement of the+additional terms that apply to those files, or a notice indicating+where to find the applicable terms.++ Additional terms, permissive or non-permissive, may be stated in the+form of a separately written license, or stated as exceptions;+the above requirements apply either way.++ 8. Termination.++ You may not propagate or modify a covered work except as expressly+provided under this License. Any attempt otherwise to propagate or+modify it is void, and will automatically terminate your rights under+this License (including any patent licenses granted under the third+paragraph of section 11).++ However, if you cease all violation of this License, then your+license from a particular copyright holder is reinstated (a)+provisionally, unless and until the copyright holder explicitly and+finally terminates your license, and (b) permanently, if the copyright+holder fails to notify you of the violation by some reasonable means+prior to 60 days after the cessation.++ Moreover, your license from a particular copyright holder is+reinstated permanently if the copyright holder notifies you of the+violation by some reasonable means, this is the first time you have+received notice of violation of this License (for any work) from that+copyright holder, and you cure the violation prior to 30 days after+your receipt of the notice.++ Termination of your rights under this section does not terminate the+licenses of parties who have received copies or rights from you under+this License. If your rights have been terminated and not permanently+reinstated, you do not qualify to receive new licenses for the same+material under section 10.++ 9. Acceptance Not Required for Having Copies.++ You are not required to accept this License in order to receive or+run a copy of the Program. Ancillary propagation of a covered work+occurring solely as a consequence of using peer-to-peer transmission+to receive a copy likewise does not require acceptance. However,+nothing other than this License grants you permission to propagate or+modify any covered work. These actions infringe copyright if you do+not accept this License. Therefore, by modifying or propagating a+covered work, you indicate your acceptance of this License to do so.++ 10. Automatic Licensing of Downstream Recipients.++ Each time you convey a covered work, the recipient automatically+receives a license from the original licensors, to run, modify and+propagate that work, subject to this License. You are not responsible+for enforcing compliance by third parties with this License.++ An "entity transaction" is a transaction transferring control of an+organization, or substantially all assets of one, or subdividing an+organization, or merging organizations. If propagation of a covered+work results from an entity transaction, each party to that+transaction who receives a copy of the work also receives whatever+licenses to the work the party's predecessor in interest had or could+give under the previous paragraph, plus a right to possession of the+Corresponding Source of the work from the predecessor in interest, if+the predecessor has it or can get it with reasonable efforts.++ You may not impose any further restrictions on the exercise of the+rights granted or affirmed under this License. For example, you may+not impose a license fee, royalty, or other charge for exercise of+rights granted under this License, and you may not initiate litigation+(including a cross-claim or counterclaim in a lawsuit) alleging that+any patent claim is infringed by making, using, selling, offering for+sale, or importing the Program or any portion of it.++ 11. Patents.++ A "contributor" is a copyright holder who authorizes use under this+License of the Program or a work on which the Program is based. The+work thus licensed is called the contributor's "contributor version".++ A contributor's "essential patent claims" are all patent claims+owned or controlled by the contributor, whether already acquired or+hereafter acquired, that would be infringed by some manner, permitted+by this License, of making, using, or selling its contributor version,+but do not include claims that would be infringed only as a+consequence of further modification of the contributor version. For+purposes of this definition, "control" includes the right to grant+patent sublicenses in a manner consistent with the requirements of+this License.++ Each contributor grants you a non-exclusive, worldwide, royalty-free+patent license under the contributor's essential patent claims, to+make, use, sell, offer for sale, import and otherwise run, modify and+propagate the contents of its contributor version.++ In the following three paragraphs, a "patent license" is any express+agreement or commitment, however denominated, not to enforce a patent+(such as an express permission to practice a patent or covenant not to+sue for patent infringement). To "grant" such a patent license to a+party means to make such an agreement or commitment not to enforce a+patent against the party.++ If you convey a covered work, knowingly relying on a patent license,+and the Corresponding Source of the work is not available for anyone+to copy, free of charge and under the terms of this License, through a+publicly available network server or other readily accessible means,+then you must either (1) cause the Corresponding Source to be so+available, or (2) arrange to deprive yourself of the benefit of the+patent license for this particular work, or (3) arrange, in a manner+consistent with the requirements of this License, to extend the patent+license to downstream recipients. "Knowingly relying" means you have+actual knowledge that, but for the patent license, your conveying the+covered work in a country, or your recipient's use of the covered work+in a country, would infringe one or more identifiable patents in that+country that you have reason to believe are valid.++ If, pursuant to or in connection with a single transaction or+arrangement, you convey, or propagate by procuring conveyance of, a+covered work, and grant a patent license to some of the parties+receiving the covered work authorizing them to use, propagate, modify+or convey a specific copy of the covered work, then the patent license+you grant is automatically extended to all recipients of the covered+work and works based on it.++ A patent license is "discriminatory" if it does not include within+the scope of its coverage, prohibits the exercise of, or is+conditioned on the non-exercise of one or more of the rights that are+specifically granted under this License. You may not convey a covered+work if you are a party to an arrangement with a third party that is+in the business of distributing software, under which you make payment+to the third party based on the extent of your activity of conveying+the work, and under which the third party grants, to any of the+parties who would receive the covered work from you, a discriminatory+patent license (a) in connection with copies of the covered work+conveyed by you (or copies made from those copies), or (b) primarily+for and in connection with specific products or compilations that+contain the covered work, unless you entered into that arrangement,+or that patent license was granted, prior to 28 March 2007.++ Nothing in this License shall be construed as excluding or limiting+any implied license or other defenses to infringement that may+otherwise be available to you under applicable patent law.++ 12. No Surrender of Others' Freedom.++ If conditions are imposed on you (whether by court order, agreement or+otherwise) that contradict the conditions of this License, they do not+excuse you from the conditions of this License. If you cannot convey a+covered work so as to satisfy simultaneously your obligations under this+License and any other pertinent obligations, then as a consequence you may+not convey it at all. For example, if you agree to terms that obligate you+to collect a royalty for further conveying from those to whom you convey+the Program, the only way you could satisfy both those terms and this+License would be to refrain entirely from conveying the Program.++ 13. Remote Network Interaction; Use with the GNU General Public License.++ Notwithstanding any other provision of this License, if you modify the+Program, your modified version must prominently offer all users+interacting with it remotely through a computer network (if your version+supports such interaction) an opportunity to receive the Corresponding+Source of your version by providing access to the Corresponding Source+from a network server at no charge, through some standard or customary+means of facilitating copying of software. This Corresponding Source+shall include the Corresponding Source for any work covered by version 3+of the GNU General Public License that is incorporated pursuant to the+following paragraph.++ Notwithstanding any other provision of this License, you have+permission to link or combine any covered work with a work licensed+under version 3 of the GNU General Public License into a single+combined work, and to convey the resulting work. The terms of this+License will continue to apply to the part which is the covered work,+but the work with which it is combined will remain governed by version+3 of the GNU General Public License.++ 14. Revised Versions of this License.++ The Free Software Foundation may publish revised and/or new versions of+the GNU Affero General Public License from time to time. Such new versions+will be similar in spirit to the present version, but may differ in detail to+address new problems or concerns.++ Each version is given a distinguishing version number. If the+Program specifies that a certain numbered version of the GNU Affero General+Public License "or any later version" applies to it, you have the+option of following the terms and conditions either of that numbered+version or of any later version published by the Free Software+Foundation. If the Program does not specify a version number of the+GNU Affero General Public License, you may choose any version ever published+by the Free Software Foundation.++ If the Program specifies that a proxy can decide which future+versions of the GNU Affero General Public License can be used, that proxy's+public statement of acceptance of a version permanently authorizes you+to choose that version for the Program.++ Later license versions may give you additional or different+permissions. However, no additional obligations are imposed on any+author or copyright holder as a result of your choosing to follow a+later version.++ 15. Disclaimer of Warranty.++ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.++ 16. Limitation of Liability.++ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF+SUCH DAMAGES.++ 17. Interpretation of Sections 15 and 16.++ If the disclaimer of warranty and limitation of liability provided+above cannot be given local legal effect according to their terms,+reviewing courts shall apply local law that most closely approximates+an absolute waiver of all civil liability in connection with the+Program, unless a warranty or assumption of liability accompanies a+copy of the Program in return for a fee.++ END OF TERMS AND CONDITIONS++ How to Apply These Terms to Your New Programs++ If you develop a new program, and you want it to be of the greatest+possible use to the public, the best way to achieve this is to make it+free software which everyone can redistribute and change under these terms.++ To do so, attach the following notices to the program. It is safest+to attach them to the start of each source file to most effectively+state the exclusion of warranty; and each file should have at least+the "copyright" line and a pointer to where the full notice is found.++ <one line to give the program's name and a brief idea of what it does.>+ Copyright (C) <year> <name of author>++ This program is free software: you can redistribute it and/or modify+ it under the terms of the GNU Affero General Public License as published+ by the Free Software Foundation, either version 3 of the License, or+ (at your option) any later version.++ This program is distributed in the hope that it will be useful,+ but WITHOUT ANY WARRANTY; without even the implied warranty of+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ GNU Affero General Public License for more details.++ You should have received a copy of the GNU Affero General Public License+ along with this program. If not, see <https://www.gnu.org/licenses/>.++Also add information on how to contact you by electronic and paper mail.++ If your software can interact with users remotely through a computer+network, you should also make sure that it provides a way for users to+get its source. For example, if your program is a web application, its+interface could display a "Source" link that leads users to an archive+of the code. There are many ways you could offer source, and different+solutions will be better for different programs; see section 13 for the+specific requirements.++ You should also get your employer (if you work as a programmer) or school,+if any, to sign a "copyright disclaimer" for the program, if necessary.+For more information on this, and how to apply and follow the GNU AGPL, see+<https://www.gnu.org/licenses/>.diff --git a/PROJECTS/beginner/deserialization-gadget-lab/README.md b/PROJECTS/beginner/deserialization-gadget-lab/README.mdnew file mode 100644index 00000000..408f87f0--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/README.md@@ -0,0 +1,79 @@+# rube++A Ruby object-deserialization security lab.++A gadget chain is a Rube Goldberg machine. One untrusted blob goes in, a dozen+unrelated standard-library methods knock each other over, and code execution falls out+the far end. This project builds the machine, then builds the thing that stops it.++## Why this exists++`Marshal.load` on untrusted input is arbitrary code execution. So is `YAML.unsafe_load`,+`JSON.load` with additions enabled, and `Oj.load` in its default mode. This is not a Ruby+quirk. It is the same class of bug as Java deserialization, PHP POP chains, and Python+pickle, and it sits at CWE-502 in the CISA Known Exploited Vulnerabilities catalog with a+**34.8% known-ransomware rate against a 20.1% baseline** across the catalog as a whole.++Most write-ups on this topic teach the exploit. Fewer teach why the obvious defense does+not work. This one does both, because the second half is where the actual lesson lives:++**You cannot make `Marshal.load` safe with an allowlist.** The `proc` you pass runs in+`r_post_proc`, which `marshal.c` invokes *after* `load_funcall(... s_mload ...)`. By the+time your allowlist sees the object, `marshal_load` has already run. The pattern widely+copied off Stack Overflow is a post-mortem, not a veto.++**Psych's allowlist genuinely is a veto** — for exactly one reason. It checks the tag+*before* revival, where Marshal checks the object *after* construction. Identical intent,+opposite outcome, decided entirely by where the check sits.++## Status++Under construction. What exists and is tested:++- **Marshal stream parser** — parses the binary format, extracts referenced class names+ and gadget sinks, and validates structure, all without ever calling `Marshal.load`.+ Rejects truncated streams, unsupported versions, unknown tags, out-of-bounds object+ links and symlinks, oversized fixnum widths, trailing bytes, and excessive nesting.++Planned: version-compatibility matrix, reflection-based gadget scanner, payload builder,+a deliberately vulnerable containerized target, and the defensive layer.++## Usage++```ruby+require "rube"++payload = Marshal.dump(Gem::Requirement.new(">= 0"))+result = Rube::Marshal::Parser.new(payload).parse++result.class_names+# => ["Gem::Requirement", "Gem::Version"]++result.sinks.map { |s| "#{s.class_name}##{s.sink_method}" }+# => ["Gem::Requirement#marshal_load", "Gem::Version#marshal_load"]+```++Nothing above instantiates a class, calls a constructor, or invokes `Marshal.load`.++## Development++Everything runs in Docker against a pinned Ruby.++```+just test run the parser suite+just control run the negative controls+just check both+just build build the gem with --strict+just manifest list exactly what would ship in the .gem+```++## A note on the object-link index++Ruby's Marshal format documentation states that object links are one-indexed. **They are+zero-indexed.** A self-referential array dumps as `04 08 5b 06 40 00`, where the trailing+`00` is a link to the outermost object at index 0. The parser is written against the+observed bytes, not the documentation.++## License++AGPL-3.0-or-later. See [LICENSE](LICENSE).diff --git a/PROJECTS/beginner/deserialization-gadget-lab/Rakefile b/PROJECTS/beginner/deserialization-gadget-lab/Rakefilenew file mode 100644index 00000000..2b78c541--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/Rakefile@@ -0,0 +1,12 @@+# ©AngelaMos | 2026+# Rakefile++require "rake/testtask"++Rake::TestTask.new(:test) do |t|+ t.libs = %w[lib test]+ t.test_files = FileList["test/**/*_test.rb"]+ t.warning = true+end++task default: :testdiff --git a/PROJECTS/beginner/deserialization-gadget-lab/justfile b/PROJECTS/beginner/deserialization-gadget-lab/justfilenew file mode 100644index 00000000..cf260a72--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/justfile@@ -0,0 +1,45 @@+# ©AngelaMos | 2026+# justfile++set shell := ["bash", "-uc"]++image := "ruby:4.0-slim"+vuln_image := "ruby:4.0.2-slim"+run := "docker run --rm --network none -v $PWD:/app -w /app " + image+run_ro := "docker run --rm --network none -v $PWD:/app:ro -w /app " + image++default:+ @just --list++test:+ {{run_ro}} ruby -Ilib -Itest test/marshal/parser_test.rb++control:+ {{run_ro}} ruby -Ilib -Itest test/control_check.rb++lint:+ {{run}} sh -c "gem install --no-document rubocop rubocop-minitest rubocop-performance rubocop-rake >/dev/null 2>&1 && rubocop --force-exclusion"++check: test control++probe:+ {{run_ro}} ruby /app/test/support/probe.rb++matrix:+ @bash scripts/version-matrix.sh++build:+ {{run}} sh -c "gem build --strict rube.gemspec"++manifest:+ {{run_ro}} ruby -e 'spec = Gem::Specification.load("rube.gemspec"); puts spec.files.sort; puts; puts "#{spec.files.length} files"'++shell:+ docker run --rm -it --network none -v $PWD:/app -w /app {{image}} bash++pull:+ docker pull {{image}}+ docker pull {{vuln_image}}++clean:+ rm -f *.gemdiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rbnew file mode 100644index 00000000..337b48c6--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rb@@ -0,0 +1,11 @@+# ©AngelaMos | 2026+# rube.rb++require_relative "rube/version"+require_relative "rube/marshal/constants"+require_relative "rube/marshal/errors"+require_relative "rube/marshal/node"+require_relative "rube/marshal/parser"++module Rube+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/constants.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/constants.rbnew file mode 100644index 00000000..2d0f1ec9--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/constants.rb@@ -0,0 +1,63 @@+# ©AngelaMos | 2026+# constants.rb++module Rube+ module Marshal+ module Constants+ MAJOR_VERSION = 4+ MINOR_VERSION = 8+ HEADER_LENGTH = 2++ TAG_NIL = "0"+ TAG_TRUE = "T"+ TAG_FALSE = "F"+ TAG_FIXNUM = "i"+ TAG_BIGNUM = "l"+ TAG_FLOAT = "f"+ TAG_STRING = '"'+ TAG_SYMBOL = ":"+ TAG_SYMLINK = ";"+ TAG_OBJECT_LINK = "@"+ TAG_ARRAY = "["+ TAG_HASH = "{"+ TAG_HASH_DEFAULT = "}"+ TAG_REGEXP = "/"+ TAG_OBJECT = "o"+ TAG_USERDEF = "u"+ TAG_USERMARSHAL = "U"+ TAG_USERCLASS = "C"+ TAG_EXTENDED = "e"+ TAG_CLASS = "c"+ TAG_MODULE = "m"+ TAG_MODULE_OLD = "M"+ TAG_STRUCT = "S"+ TAG_DATA = "d"+ TAG_IVAR = "I"++ BIGNUM_SIGN_POSITIVE = "+"+ BIGNUM_SIGN_NEGATIVE = "-"+ BIGNUM_WORD_BYTES = 2++ FIXNUM_INLINE_OFFSET = 5+ FIXNUM_MAX_INLINE = 4+ FIXNUM_MIN_INLINE = -4+ FIXNUM_MAX_WIDTH = 4++ BYTE_SIGN_THRESHOLD = 128+ BYTE_MODULUS = 256+ BITS_PER_BYTE = 8++ DEFAULT_MAX_DEPTH = 256++ SINK_TAGS = [TAG_USERDEF, TAG_USERMARSHAL, TAG_DATA].freeze++ SINK_METHODS = {+ TAG_USERDEF => "_load",+ TAG_USERMARSHAL => "marshal_load",+ TAG_DATA => "_load_data"+ }.freeze++ GATED_SINK_TAGS = [TAG_USERDEF, TAG_USERMARSHAL].freeze+ end+ end+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/errors.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/errors.rbnew file mode 100644index 00000000..5817ad95--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/errors.rb@@ -0,0 +1,20 @@+# ©AngelaMos | 2026+# errors.rb++module Rube+ module Marshal+ class StreamError < StandardError; end++ class TruncatedStreamError < StreamError; end++ class UnsupportedVersionError < StreamError; end++ class UnknownTagError < StreamError; end++ class TrailingBytesError < StreamError; end++ class InvalidLinkError < StreamError; end++ class DepthLimitError < StreamError; end+ end+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/node.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/node.rbnew file mode 100644index 00000000..34fa1f03--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/node.rb@@ -0,0 +1,64 @@+# ©AngelaMos | 2026+# node.rb++module Rube+ module Marshal+ class Node+ attr_reader :type, :tag, :children, :instance_variables_map+ attr_accessor :value, :class_name++ def initialize(type:, tag: nil, value: nil, class_name: nil)+ @type = type+ @tag = tag+ @value = value+ @class_name = class_name+ @children = []+ @instance_variables_map = {}+ end++ def sink?+ Constants::SINK_TAGS.include?(tag)+ end++ def sink_method+ Constants::SINK_METHODS[tag]+ end++ def gated?+ Constants::GATED_SINK_TAGS.include?(tag)+ end++ def each(&block)+ return enum_for(:each) unless block++ yield self+ children.each { |child| child.each(&block) }+ instance_variables_map.each_value { |child| child.each(&block) }+ end+ end++ class Result+ attr_reader :root++ def initialize(root)+ @root = root+ end++ def nodes+ root.each+ end++ def class_names+ nodes.filter_map(&:class_name).uniq+ end++ def sinks+ nodes.select(&:sink?)+ end++ def gated_sinks+ sinks.select(&:gated?)+ end+ end+ end+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/parser.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/parser.rbnew file mode 100644index 00000000..1eafff04--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/marshal/parser.rb@@ -0,0 +1,231 @@+# ©AngelaMos | 2026+# parser.rb++module Rube+ module Marshal+ class Parser+ include Constants++ def initialize(source, max_depth: DEFAULT_MAX_DEPTH)+ @source = source.to_s.dup.force_encoding(Encoding::BINARY)+ @max_depth = max_depth+ @position = 0+ @symbols = []+ @objects = []+ end++ def parse+ read_header+ root = read_value(1)+ raise TrailingBytesError, "#{remaining} unread bytes" unless remaining.zero?++ Result.new(root)+ end++ private++ attr_reader :source, :max_depth, :symbols, :objects++ def remaining+ source.bytesize - @position+ end++ def take(count)+ raise TruncatedStreamError, "wanted #{count} bytes, had #{remaining}" if count > remaining++ slice = source.byteslice(@position, count)+ @position += count+ slice+ end++ def take_byte+ take(1).unpack1("C")+ end++ def take_signed_byte+ byte = take_byte+ byte >= BYTE_SIGN_THRESHOLD ? byte - BYTE_MODULUS : byte+ end++ def read_header+ header = take(HEADER_LENGTH)+ major, minor = header.unpack("CC")+ return if major == MAJOR_VERSION && minor <= MINOR_VERSION++ raise UnsupportedVersionError, "stream declares #{major}.#{minor}"+ end++ def read_fixnum+ marker = take_signed_byte+ return 0 if marker.zero?+ return marker - FIXNUM_INLINE_OFFSET if marker > FIXNUM_MAX_INLINE+ return marker + FIXNUM_INLINE_OFFSET if marker < FIXNUM_MIN_INLINE++ width = marker.abs+ raise TruncatedStreamError, "fixnum width #{width}" if width > FIXNUM_MAX_WIDTH++ value = little_endian(take(width))+ marker.negative? ? value - (1 << (BITS_PER_BYTE * width)) : value+ end++ def little_endian(bytes)+ bytes.each_byte.with_index.sum { |byte, index| byte << (BITS_PER_BYTE * index) }+ end++ def read_counted_bytes+ take(read_fixnum)+ end++ def register(node)+ objects << node+ node+ end++ def read_value(depth)+ raise DepthLimitError, "exceeded depth #{max_depth}" if depth > max_depth++ tag = take(1)++ case tag+ when TAG_NIL then Node.new(type: :nil, tag: tag)+ when TAG_TRUE then Node.new(type: :boolean, tag: tag, value: true)+ when TAG_FALSE then Node.new(type: :boolean, tag: tag, value: false)+ when TAG_FIXNUM then Node.new(type: :fixnum, tag: tag, value: read_fixnum)+ when TAG_SYMBOL then read_symbol(tag)+ when TAG_SYMLINK then read_symlink(tag)+ when TAG_OBJECT_LINK then read_object_link(tag)+ when TAG_BIGNUM then register(read_bignum(tag))+ when TAG_FLOAT then register(read_float(tag))+ when TAG_STRING then register(read_string(tag))+ when TAG_REGEXP then register(read_regexp(tag))+ when TAG_ARRAY then read_array(tag, depth)+ when TAG_HASH, TAG_HASH_DEFAULT then read_hash(tag, depth)+ when TAG_IVAR then read_ivar(tag, depth)+ when TAG_OBJECT then read_object(tag, depth)+ when TAG_STRUCT then read_struct(tag, depth)+ when TAG_USERDEF then register(read_userdef(tag))+ when TAG_USERMARSHAL then read_usermarshal(tag, depth)+ when TAG_DATA then read_wrapped(tag, :data, depth)+ when TAG_USERCLASS then read_wrapped(tag, :user_class, depth)+ when TAG_EXTENDED then read_wrapped(tag, :extended, depth)+ when TAG_CLASS then register(read_named(tag, :class))+ when TAG_MODULE, TAG_MODULE_OLD then register(read_named(tag, :module))+ else raise UnknownTagError, "byte #{tag.unpack1('C')} at offset #{@position - 1}"+ end+ end++ def read_symbol(tag)+ node = Node.new(type: :symbol, tag: tag, value: read_counted_bytes.to_sym)+ symbols << node.value+ node+ end++ def read_symlink(tag)+ index = read_fixnum+ raise InvalidLinkError, "symlink #{index} of #{symbols.length}" unless symbols[index] && index >= 0++ Node.new(type: :symlink, tag: tag, value: symbols[index])+ end++ def read_object_link(tag)+ index = read_fixnum+ raise InvalidLinkError, "object link #{index} of #{objects.length}" unless objects[index] && index >= 0++ Node.new(type: :object_link, tag: tag, value: index)+ end++ def read_bignum(tag)+ negative = take(1) == BIGNUM_SIGN_NEGATIVE+ magnitude = little_endian(take(read_fixnum * BIGNUM_WORD_BYTES))+ Node.new(type: :bignum, tag: tag, value: negative ? -magnitude : magnitude)+ end++ def read_float(tag)+ Node.new(type: :float, tag: tag, value: Float(read_counted_bytes))+ rescue ArgumentError+ Node.new(type: :float, tag: tag)+ end++ def read_string(tag)+ Node.new(type: :string, tag: tag, value: read_counted_bytes)+ end++ def read_regexp(tag)+ node = Node.new(type: :regexp, tag: tag, value: read_counted_bytes)+ take(1)+ node+ end++ def read_array(tag, depth)+ node = register(Node.new(type: :array, tag: tag))+ read_fixnum.times { node.children << read_value(depth + 1) }+ node+ end++ def read_hash(tag, depth)+ node = register(Node.new(type: :hash, tag: tag))+ read_fixnum.times { node.children << read_pair(depth) }+ node.children << read_value(depth + 1) if tag == TAG_HASH_DEFAULT+ node+ end++ def read_pair(depth)+ pair = Node.new(type: :pair)+ pair.children << read_value(depth + 1)+ pair.children << read_value(depth + 1)+ pair+ end++ def read_ivar(tag, depth)+ inner = read_value(depth)+ read_fixnum.times do+ name = read_value(depth + 1)+ inner.instance_variables_map[name.value] = read_value(depth + 1)+ end+ inner+ end++ def read_object(tag, depth)+ node = register(Node.new(type: :object, tag: tag))+ node.class_name = read_value(depth + 1).value.to_s+ read_fixnum.times do+ name = read_value(depth + 1)+ node.instance_variables_map[name.value] = read_value(depth + 1)+ end+ node+ end++ def read_struct(tag, depth)+ node = register(Node.new(type: :struct, tag: tag))+ node.class_name = read_value(depth + 1).value.to_s+ read_fixnum.times { node.children << read_pair(depth) }+ node+ end++ def read_userdef(tag)+ node = Node.new(type: :userdef, tag: tag)+ node.class_name = read_value(1).value.to_s+ node.value = read_counted_bytes+ node+ end++ def read_usermarshal(tag, depth)+ node = register(Node.new(type: :usermarshal, tag: tag))+ node.class_name = read_value(depth + 1).value.to_s+ node.children << read_value(depth + 1)+ node+ end++ def read_wrapped(tag, type, depth)+ node = register(Node.new(type: type, tag: tag))+ node.class_name = read_value(depth + 1).value.to_s+ node.children << read_value(depth + 1)+ node+ end++ def read_named(tag, type)+ Node.new(type: type, tag: tag, class_name: read_counted_bytes)+ end+ end+ end+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/version.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/version.rbnew file mode 100644index 00000000..2af11c23--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/version.rb@@ -0,0 +1,6 @@+# ©AngelaMos | 2026+# version.rb++module Rube+ VERSION = "0.1.0"+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/rube.gemspec b/PROJECTS/beginner/deserialization-gadget-lab/rube.gemspecnew file mode 100644index 00000000..35c2b86d--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/rube.gemspec@@ -0,0 +1,37 @@+# ©AngelaMos | 2026+# rube.gemspec++require_relative "lib/rube/version"++Gem::Specification.new do |spec|+ spec.name = "rube"+ spec.version = Rube::VERSION+ spec.authors = ["Carter Perez"]+ spec.email = ["[email protected]"]++ spec.summary = "Ruby object-deserialization security lab: inspect, understand, and defend against gadget chains"+ spec.description = "rube parses Ruby Marshal streams without deserializing them, discovers gadget " \+ "sinks by runtime reflection, and ships the defenses that stop them. Built as a " \+ "teaching artifact for the deserialization vulnerability class."+ spec.homepage = "https://github.com/CarterPerez-dev/Cybersecurity-Projects"+ spec.license = "AGPL-3.0-or-later"++ spec.required_ruby_version = ">= 3.3"++ spec.metadata = {+ "source_code_uri" => "#{spec.homepage}/tree/main/PROJECTS/beginner/deserialization-gadget-lab",+ "bug_tracker_uri" => "#{spec.homepage}/issues",+ "changelog_uri" => "#{spec.homepage}/blob/main/PROJECTS/beginner/deserialization-gadget-lab/CHANGELOG.md",+ "documentation_uri" => "#{spec.homepage}/tree/main/PROJECTS/beginner/deserialization-gadget-lab/learn",+ "rubygems_mfa_required" => "true"+ }++ spec.files = Dir[+ "lib/**/*.rb",+ "README.md",+ "CHANGELOG.md",+ "LICENSE"+ ]++ spec.require_paths = ["lib"]+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rb b/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rbnew file mode 100644index 00000000..409e3f41--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rb@@ -0,0 +1,78 @@+# ©AngelaMos | 2026+# control_check.rb++require_relative "test_helper"++Pair = Struct.new(:x, :y)++puts "=== control 1: does the TracePoint oracle actually fire on a real Marshal.load ==="+fired = false+tracer = TracePoint.new(:call, :c_call) do |tp|+ fired = true if tp.method_id == :load && tp.self.equal?(Marshal)+end+tracer.enable { Marshal.load(Marshal.dump([1, 2])) }+puts fired ? " FIRED - oracle is live, the never-calls-load test is meaningful" : " DID NOT FIRE - oracle is broken, that test proves nothing"++puts+puts "=== control 2: object link index actually present in the stream ==="+cyclic = []+cyclic << cyclic+blob = Marshal.dump(cyclic)+puts " bytes: #{blob.bytes.map { |b| format('%02x', b) }.join(' ')}"+puts " ascii: #{blob.inspect}"+link = Rube::Marshal::Parser.new(blob).parse.root.children.first+puts " parsed link index: #{link.value} (must be 0, docs claim 1)"++puts+puts "=== control 3: broad corpus round-trip, parser vs Marshal ground truth ==="+shared = "shared"+aliased = [shared, shared]+cyclic_hash = {}+cyclic_hash[:self] = cyclic_hash+deep = [1]+20.times { deep = [deep] }++corpus = [+ nil, true, false,+ 0, 1, -1, 122, 123, -123, -124, 255, -256, 65_536, -65_536,+ 1_073_741_823, -1_073_741_824, 2**70, -(2**70), 2**200,+ 0.0, -0.0, 3.14, Float::INFINITY, -Float::INFINITY,+ "", "str", "\x00\xff binary".b, "unicode Ă©ä¸",+ :sym, :"with spaces", :marshal_load,+ [], {}, [1, [2, [3, [4]]]], { a: { b: { c: 1 } } },+ (1..5).to_a, Pair.new(1, 2), Pair.new(nil, [1, 2]),+ Object.new, Time.now, /regex/i, //mx, String, Comparable, Rube,+ aliased, cyclic_hash, deep,+ { "mixed" => [1, :two, 3.0, nil, true] },+ Hash.new(0).tap { |h| h[:k] = 1 },+ Gem::Requirement.new(">= 0"), Gem::Version.new("1.2.3")+]+ok = 0+corpus.each do |item|+ blob = Marshal.dump(item)+ result = Rube::Marshal::Parser.new(blob).parse+ raise "no root for #{item.inspect}" unless result.root++ ok += 1+rescue StandardError => e+ puts " FAIL #{item.class}: #{e.class}: #{e.message}"+end+puts " #{ok}/#{corpus.length} parsed without Marshal.load"++puts+puts "=== control 4: mutation - break the link bounds check, does a test catch it ==="+puts " (verified manually below by feeding an out-of-range link)"+begin+ Rube::Marshal::Parser.new("\x04\x08[\x06@\x63").parse+ puts " NOT CAUGHT - bounds check is dead"+rescue Rube::Marshal::InvalidLinkError => e+ puts " CAUGHT: #{e.message}"+end++puts+puts "=== control 5: real gadget-shaped payload, class names extracted, nothing built ==="+payload = Marshal.dump(Gem::Requirement.new(">= 0"))+result = Rube::Marshal::Parser.new(payload).parse+puts " classes: #{result.class_names.inspect}"+puts " sinks: #{result.sinks.map { |s| "#{s.class_name}##{s.sink_method}" }.inspect}"+puts " gated: #{result.gated_sinks.map(&:class_name).inspect}"diff --git a/PROJECTS/beginner/deserialization-gadget-lab/test/marshal/parser_test.rb b/PROJECTS/beginner/deserialization-gadget-lab/test/marshal/parser_test.rbnew file mode 100644index 00000000..4ce6c90f--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/test/marshal/parser_test.rb@@ -0,0 +1,227 @@+# ©AngelaMos | 2026+# parser_test.rb++require_relative "../test_helper"++module Rube+ module Marshal+ class ParserTest < Minitest::Test+ def parse(blob)+ Parser.new(blob).parse+ end++ def roundtrip(object)+ parse(::Marshal.dump(object)).root+ end++ def test_rejects_empty_stream+ assert_raises(TruncatedStreamError) { parse("") }+ end++ def test_rejects_header_only+ assert_raises(TruncatedStreamError) { parse("\x04\x08") }+ end++ def test_rejects_wrong_major_version+ assert_raises(UnsupportedVersionError) { parse("\x05\x08\x30") }+ end++ def test_rejects_future_minor_version+ assert_raises(UnsupportedVersionError) { parse("\x04\x09\x30") }+ end++ def test_accepts_older_minor_version+ assert_equal :nil, parse("\x04\x07\x30").root.type+ end++ def test_rejects_unknown_tag+ assert_raises(UnknownTagError) { parse("\x04\x08\x00") }+ end++ def test_rejects_trailing_bytes+ assert_raises(TrailingBytesError) { parse(::Marshal.dump(nil) + "junk") }+ end++ def test_parses_nil+ assert_equal :nil, roundtrip(nil).type+ end++ def test_parses_booleans+ assert_equal true, roundtrip(true).value+ assert_equal false, roundtrip(false).value+ end++ def test_parses_fixnum_across_every_encoding_width+ [0, 1, 5, 122, 123, 255, 256, 65_535, 65_536, 1_073_741_823,+ -1, -123, -124, -256, -65_536, -1_073_741_824].each do |n|+ assert_equal n, roundtrip(n).value, "fixnum #{n} did not round-trip"+ end+ end++ def test_parses_bignum_both_signs+ [2**64, -(2**64), 2**128 + 7].each do |n|+ assert_equal n, roundtrip(n).value, "bignum #{n} did not round-trip"+ end+ end++ def test_parses_float+ assert_in_delta 3.5, roundtrip(3.5).value, 0.0+ end++ def test_parses_symbol+ assert_equal :marshal_load, roundtrip(:marshal_load).value+ end++ def test_parses_string_through_ivar_wrapper+ node = roundtrip("hello")+ assert_equal :string, node.type+ assert_equal "hello", node.value+ end++ def test_parses_array+ node = roundtrip([1, 2, 3])+ assert_equal :array, node.type+ assert_equal [1, 2, 3], node.children.map(&:value)+ end++ def test_parses_nested_array+ node = roundtrip([1, [2, [3]]])+ assert_equal 3, node.children.last.children.last.children.first.value+ end++ def test_parses_hash+ node = roundtrip({ a: 1 })+ assert_equal :hash, node.type+ assert_equal 1, node.children.length+ end++ def test_object_links_are_zero_indexed+ cyclic = []+ cyclic << cyclic+ node = roundtrip(cyclic)+ link = node.children.first+ assert_equal :object_link, link.type+ assert_equal 0, link.value+ end++ def test_rejects_out_of_bounds_object_link+ assert_raises(InvalidLinkError) { parse("\x04\x08@\x0a") }+ end++ def test_rejects_out_of_bounds_symlink+ assert_raises(InvalidLinkError) { parse("\x04\x08;\x0a") }+ end++ def test_resolves_symlink_to_prior_symbol+ node = roundtrip([:same, :same])+ assert_equal :symlink, node.children.last.type+ assert_equal :same, node.children.last.value+ end++ def test_extracts_class_name_from_plain_object+ blob = ::Marshal.dump(Fixture.new)+ result = parse(blob)+ assert_includes result.class_names, "Rube::Marshal::ParserTest::Fixture"+ end++ def test_extracts_class_name_without_instantiating+ refute Fixture.instantiated, "parser must not construct the class"+ parse(::Marshal.dump(Fixture.new))+ refute Fixture.instantiated, "parser instantiated a class during parse"+ end++ def test_flags_usermarshal_as_sink+ result = parse(::Marshal.dump(UserMarshalFixture.new))+ sink = result.sinks.first+ refute_nil sink+ assert_equal "marshal_load", sink.sink_method+ assert_equal "Rube::Marshal::ParserTest::UserMarshalFixture", sink.class_name+ end++ def test_flags_userdef_as_sink+ result = parse(::Marshal.dump(UserDefFixture.new))+ assert_equal "_load", result.sinks.first.sink_method+ end++ def test_clean_payload_reports_no_sinks+ assert_empty parse(::Marshal.dump([1, "two", :three, { a: 1 }])).sinks+ end++ def test_rejects_truncated_string_body+ assert_raises(TruncatedStreamError) { parse("\x04\x08\"\x0aab") }+ end++ def test_rejects_truncated_array_elements+ assert_raises(TruncatedStreamError) { parse("\x04\x08[\x08i\x06") }+ end++ def test_rejects_truncated_multibyte_fixnum+ assert_raises(TruncatedStreamError) { parse("\x04\x08i\x03\x01") }+ end++ def test_rejects_depth_beyond_limit+ deep = "\x04\x08" + ("[\x06" * (Constants::DEFAULT_MAX_DEPTH + 5)) + "0"+ assert_raises(DepthLimitError) { parse(deep) }+ end++ def test_honours_custom_depth_limit+ blob = ::Marshal.dump([[[1]]])+ assert_raises(DepthLimitError) { Parser.new(blob, max_depth: 2).parse }+ end++ def load_watcher+ fired = false+ tracer = TracePoint.new(:call, :c_call) do |tp|+ fired = true if tp.method_id == :load && tp.self.equal?(::Marshal)+ end+ tracer.enable { yield }+ fired+ end++ def test_load_watcher_oracle_is_live+ assert load_watcher { ::Marshal.load(::Marshal.dump([1, 2])) },+ "oracle failed to observe a real Marshal.load, so the next test would pass vacuously"+ end++ def test_never_calls_marshal_load+ blob = ::Marshal.dump(UserMarshalFixture.new)+ refute load_watcher { parse(blob) }, "parser invoked Marshal.load"+ end++ def test_never_calls_marshal_load_on_gadget_shaped_payload+ blob = ::Marshal.dump(Gem::Requirement.new(">= 0"))+ refute load_watcher { parse(blob) }, "parser invoked Marshal.load"+ end++ class Fixture+ @instantiated = false++ class << self+ attr_accessor :instantiated+ end++ def initialize+ @marker = "value"+ end+ end++ class UserMarshalFixture+ def marshal_dump+ ["payload"]+ end++ def marshal_load(data); end+ end++ class UserDefFixture+ def _dump(_depth)+ "opaque"+ end++ def self._load(_data)+ new+ end+ end+ end+ end+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/test/test_helper.rb b/PROJECTS/beginner/deserialization-gadget-lab/test/test_helper.rbnew file mode 100644index 00000000..bdefdac0--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/test/test_helper.rb@@ -0,0 +1,7 @@+# ©AngelaMos | 2026+# test_helper.rb++$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))++require "minitest/autorun"+require "rube"